Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Scout/Contributions for Scout Committers

< Scout
Revision as of 09:45, 8 July 2013 by Judith.gull.gmail.com (Talk | contribs) (Push changes to remote repository (Gerrit))

Initial Setup

In order to work efficiently as a scout committer you need to setup your tools correctly. Here, we try to describe a setup that is simple and working. You only need to do this once.

Git repositories

All Eclipse Scout Git repositories are listed under http://git.eclipse.org/c/scout/.

org.eclipse.scout-aggregator.git  //used for building and aggregation (p2 repositories) and deployment
org.eclipse.scout.rt.git          //Scout Runtime
org.eclipse.scout.sdk.git         //Scout Tooling
scout.rt.incubator.git            //Scout Incubation Components (currently only runtime)

You need to clone all repositories that you need for your daily work. Because we are using Gerrit for code review, you need to setup this as well.

Clone Git repositories

Here is a step-by-step guide how to clone a repository. We use Scout RT as an example:

In your Eclipse IDE click on Windows -> Open Perspective -> Others... and select Git Repository Exploring. In the GIT perspective, click on Clone a Git repository and select URI as a repository source in the next dialog.

GitContribution.01.select.git.perspective.png GitContribution.02.clone.git.perspective.png

For the Scout RT repository we use the GIT protocol:

git://git.eclipse.org/gitroot/scout/org.eclipse.scout.rt.git

The GIT url is listed under Clone on the webpage of the repository: http://git.eclipse.org/c/scout/org.eclipse.scout.rt.git/. Since we are interested in the develop and release/3.9.1 (Kepler SR1) branches, we only select these two branches.

GitContribution CloneGitRepoUrl.jpg GitContribution.04.select.remote.branches.png

The Scout RT GIT repository will be cloned to a local destination. Choose C:\Users\<username>\git\<repositoryName>. Choose develop as the initial branch and enter origin to reference the remote GIT repository. Finally, click on Finish to clone the Scout RT repository.

GitContribution.05.choose.local.destination.png

Gerrit Configuration

Although it is possible to push direclty to git, the common process is to push to Gerrit. We do this because

  • A build is triggered automatically after a commit. You will be notified when the build is started and completed. That way we make sure that no commits that break the build or tests are submitted unnoticed.
  • A commit can be reviewed and updated, if necessary.

Gerrit @Eclipse can be found here: https://git.eclipse.org/r/. The sandbox hudson for gerrit is located here: https://hudson.eclipse.org/sandbox/. It contains jobs for eclipse.scout.rt and eclipse.scout.sdk.

Gerrit Settings

Gerrit is located here: https://git.eclipse.org/r/. Sign in with your email and password. In order to push your changes to git you need to upload an ssh key.

TODO

Gerrit Push Configuration

In the previous step we cloned our Scout RT repository read-only. To be able to push our feature branches and patches, we have to configure the Push URL to use Gerrit where write access is granted. Therefore we change the push URL to point to Gerrit:

ssh://[username]@git.eclipse.org:29418/scout/[repository_name].git

[username] is your committer Id. E.g.

ssh://jgull@git.eclipse.org:29418/scout/org.eclipse.scout.rt.git

Expand the Remotes directory, right-click on origin and select Gerrit Configuration....

GitContributionStep4.01.configure.push.url.png GitContributionStep4.02.add.gerrit.png

Click on Finish. Your Push URL should now look similar like

GitContributionStep4.03.gerrit.added.png

Import Plugins Projects into Workspace

The sources are not stored in your workspace. You may create multiple workspaces for different purposes and use the sources stored in the local git repository. You most probably need one workspace for scout.rt and import all runtime plugins.

Double-click on the cloned repository org.eclipse.scout.rt and right-click on the Working Directory and select Import Projects.... Import Existing Projects and select all plugins. Click on Finish to start the import process.

GitContributionStep2.01.import.into.workspace.png GitContributionStep2.02.import.into.workspace.wizard.png GitContributionStep2.03.select.plugins.png

Contributing Code

When contributing features and patches you first need to think about on what release and branch it needs to be committed. An overview on branches is described here: Scout/Contribution_Guidelines#Git_Branching_Policy. A developer will usually one of the following:

  1. New feature: New features are only applied to the latest release. (If you think you have a "feature" that needs to be applied to a service release, let us call it hotfix.)
  2. Hotfix: An important bugfix that needs to be applied to the latest release and one or more older branches.
  3. Minor Bugfix: An minor bugfix that does not need to be applied to an older release.

The scenarios 1 and 2 are described here. 3 is done the same way as 1.

Contributing a new Feature

When you create a new feature you need to consider the following branches:

local branches:
 develop // local branch for HEAD
 features/<committerId>/<featureName>_<bugzillaid> //created by you for work in progress on your local machine
remote branches:
 develop // your feature ultimately needs to be pushed here
 features/<committerId>/<featureName>_<bugzillaid> //created by you for work in progress

For every new feature we create a new branch. We do that because

  • All changes of that feature are in the same place separate from the develop branch. We should have a better overview.
  • We can share it with other developers before it is complete. We can make sure that only complete features are pushed to the develop branch.
  • Working on multiple features in parallel is possible
  • It is not much additional overhead

Get the latest changes

Before we start we make sure we have the latest changes:

  • Checkout the local develop branch by double clicking it
  • Fetch the latest changes: Right-click the git repository and choose Fetch from Upstream
  • Pull: Right-click the git repository and choose Pull

Take a look at commit history (optional)

We can look at the commit history to see, if everything is as expected. Expand your local branches, right-click on develop and choose Show In -> History. We can see that our local 'develop branch (marked in green) refers to the same last commit as the remote develop branch shown as origin/develop in grey.


GitContributionStep3.01.show.history.png GitContributionStep3.02.history.timeline.png

Create a local feature branch

We create and checkout a new local feature branch based on origin/develop with pull strategy None. We call the local feature branch description_bugzillaId, e.g. luna_target_bug412011.

Right-click on the commit where the origin/develop branch is pointing to and select Create Branch.... As Source ref or commit we select refs/remotes/origin/develop and call the local feature branch luna_target_bug412011. Select None as pull strategy and check Checkout new branch. Click on Finish. The feature branch should now be created locally.

GitContributionStep3.03.create.branch.png GitContributionStep3.03.create.new.feature.branch.png

The black checkbox icon on the left and the bold font in the History view indicate that the feature branch is currently active (checked out).

GitContributionStep3.03.feature.branch.created.png

Push feature branch to remote repository

Now we push the recently created local feature branch to the remote repository on a remote feature branch. We do this to backup our work and allow other people to work on this feature. We also trigger a build on the sandbox hudson to verify the changes.

Right-click on the local feature branch luna_target_bug412011 and select Push Branch.... The remote repository should already be the correct Gerrit Push URL. Press Next.

GitContributionStep5.01.push.feature.branch.to.remote.small.png GitContributionStep5.02.select.remote.repository.png

Now we choose the target ref name for the feature branch. The convention is as follow: refs/heads/features/[committerID]/shortDescription_bug[ID], where [committerID] and [ID] should be replaced by the actual value. Press Finish and the feature branch should now be pushed onto the remote repository. There should be no error.

GitContributionStep5.03.choose.target.ref.name.png GitContributionStep5.05.feature.branch.added.png

The feature branch is visible in the Remote Tracking directory.

Commit changes to local feature branch

Now we do some changes and commit on the local feature branch.

In our example we made some initial changes for bug 412011 and are now about to commit a new file into the local branch. Switch to the view Git Staging. In the Unstaged Changes area all new and modified files are listed. We move the new eclipse-3.10I.target to the Staged Changes area by using drag-and-drop and enter a commit message.

GitContributionStep6.01.commit.to.local.branch.png GitContributionStep6.02.stage.and.enter.commit.message.png

Now we press the button Commit so that the target file will be committed into the local feature branch (Note: If we pressed the button Commit and Push, we would commit the target file into the local feature branch and also push those changes to the feature branch on the remote repository. However, we will do this step manually in this example).

If we look at the Commit History, we see that the local feature branch luna_target_bug412011 is 1 commit ahead of the remote feature branch origin/features/klee1/lunaTarget_bug412011.

GitContributionStep6.03.commit.history.png

Push changes to remote feature branch (Gerrit)

Next, we push to local feature branch into the feature branch of the remote repository. Right-click on the Scout RT Git repository and select Push to Gerrit...

GitContributionStep6.04.push.to.gerrit.png

In the URI field select Gerrit (the one containing git.eclipse.org:29418) and in the field Gerrit branch select refs/for/ and hit Ctrl+Space in the text field to open a pop-up dialog. Select your remote feature branch and press Finish.

GitContributionStep6.05.push.to.gerrit.dialog.png

The prefix refs/for indicates a special branch for Gerrit code review. The changes in the local feature branch will not directly be pushed into the feature branch of the remote repository. Instead, the changes are made available in Gerrit where code review can be done. In our example, the URL for code review is displayed Message Details box.

GitContributionStep6.06.gerrit.url.for.code.review.png

Review Changes on Gerrit

This URL can be opened in a browser. The Sandbox Hudson will verify the supplied changes and set the verified flag if the build was successful.

GitContributionStep6.07.gerrit.in.browser.png

After reviewing the code, the changes can be merged into the feature branch by clicking on the button Review and setting Code-Review +2 and IP-Clean to +1 and pressing Publish and Submit.

GitContributionStep6.08.gerrit.publish.and.submit.png

Switch back to EGit, right-click on the Scout RT Git repository and select Fetch from Upstream.

GitContributionStep6.09.fetch.from.upstream.png

All branches will be fetched, i.e. our remote feature branch should be updated and be visible in the Commit History (Note: For the sake of simplicity we removed all irrelevant branches from the remote tracking folder). Currently, the local feature branch and the remote feature branch point to different commits, however they both contain the same changes. Therefore, we are going to rebase our local feature branch on top of the remote feature branch. Right-click on the remote feature branch and select Rebase on Top of.

GitContributionStep6.10.rebase.png

The local feature branch and remote should now point to the same commit ID.

GitContributionStep6.11.after.rebase.png

Apply commits from feature branch to develop

Before we apply our changes from the feature branch to the develop branch (currently the Scout Luna branch), we decide to make some further changes, commit them into the local feature branch and push them to Gerrit again (please repeat step 6). The new changes for our example are available here. As before, we review and apply these changes into the remote feature branch resulting the Commit History view to display something like this:

GitContributionStep7.01.commit.history.png

We now have two commits in our feature branch (remote and local) and both of them will be applied to to the origin/develop branch as 1 commit, i.e. in the Git context we squash our 2 commits from the feature branch into 1. To achieve this goal we reset our local feature branch luna_target_bug412011 to the remote origin/develop branch by right-clicking and select Reset -> Mixed (HEAD and Index).

GitContributionStep7.02.reset.mixed.png

Reset-Mixed means that the changes from the feature branch will be made available as Unstaged Changes. In the Git Staging perspective we move the changes to the Staged Changes area and commit them locally.

GitContributionStep7.03.squash.commit.png

The Commit History looks like:

GitContributionStep7.04.commit.history.after.commit.png

The local feature branch luna_target_bug412011 is now 1 commit ahead of the origin/develop branch, so we push this commit to Gerrit as follows: Select Push to Gerrit... and configure the dialog like this:

GitContributionStep7.05.push.to.gerrit.develop.branch.png

Hit Ctrl+Space in the Gerrit Branch field and choose develop branch, select refs/for/ in the drop-down field. After a successful code review at Gerrit, we apply this change into the remote develop branch.

After fetching the remote branches the Commit History should now display a new commit on the origin/develop branch.

GitContributionStep7.06.commit.history.after.merging.png

Contributing a new Patch

Assume we want to provide an implementation for bug 412011. We will create a local branch first based on the latest commit of the develop branch. Then we apply some initial changes for the bug, commit them to the local branch and will push the local feature branch to the remote Git repository (origin). Afterwards, we will do some further changes, commit them locally and push these changes to the recently created remote branch.

First, we will have a look at the Commit History. In the Git perspective expand your local branches and right click on the develop branch and choose Show In -> History.

GitContributionStep3.01.show.history.png

The History view should be opened and it should look something like

GitContributionStep3.02.history.timeline.png

We can see that our local 'develop branch (marked in green) refers to the same last commit as the remote develop branch shown as origin/develop in grey. Right-click on the commit where the origin/develop branch is pointing to and select Create Branch....

GitContributionStep3.03.create.branch.png

As Source ref or commit we select refs/remotes/origin/develop and call the local feature branch luna_target_bug412011. Select None as pull strategy and check Checkout new branch.

GitContributionStep3.03.create.new.feature.branch.png

Click on Finish. The feature branch should now be created locally.

GitContributionStep3.03.feature.branch.created.png

The black checkbox icon on the left and the bold font in the History view indicate that the feature branch is currently active.

Push feature branch to remote repository

Now we push the recently created local feature branch to the remote repository. Right-click on the local feature branch luna_target_bug412011 and select Push Branch....

GitContributionStep5.01.push.feature.branch.to.remote.png

Select the remote repository which corresponds to the Gerrit Push URL we've just added in the previous step. Press Next.

GitContributionStep5.02.select.remote.repository.png

Now we choose the target ref name for the feature branch. The convention is as follow: refs/heads/features/[committerID]/shortDescription_bug[ID], where [committerID] and [ID] should be replaced by the actual value.

GitContributionStep5.03.choose.target.ref.name.png

Press Finish and the feature branch should now be pushed onto the remote repository.

GitContributionStep5.04.feature.branch.pushed.png

The feature branch is visible in the Remote Tracking directory.

GitContributionStep5.05.feature.branch.added.png

Commit changes to local feature branch and push to remote repository

In our example we made some initial changes for bug 412011 and are now about to commit a new file into the local branch. Switch to the view Git Staging.

GitContributionStep6.01.commit.to.local.branch.png

In the Unstaged Changes area all new and modified files are listed. We move the new eclipse-3.10I.target to the Staged Changes area by using drag-and-drop and enter a commit message.

GitContributionStep6.02.stage.and.enter.commit.message.png

Now we press the button Commit so that the target file will be committed into the local feature branch (Note: If we pressed the button Commit and Push, we would commit the target file into the local feature branch and also push those changes to the feature branch on the remote repository. However, we will do this step manually in this example).

If we look at the Commit History, we see that the local feature branch luna_target_bug412011 is 1 commit ahead of the remote feature branch origin/features/klee1/lunaTarget_bug412011.

GitContributionStep6.03.commit.history.png

Next, we push to local feature branch into the feature branch of the remote repository. Right-click on the Scout RT Git repository and select Push to Gerrit...

GitContributionStep6.04.push.to.gerrit.png

In the URI field select Gerrit (the one containing git.eclipse.org:29418) and in the field Gerrit branch select refs/for/ and hit Ctrl+Space in the text field to open a pop-up dialog. Select your remote feature branch and press Finish.

GitContributionStep6.05.push.to.gerrit.dialog.png

The prefix refs/for indicates a special branch for Gerrit code review. The changes in the local feature branch will not directly be pushed into the feature branch of the remote repository. Instead, the changes are made available in Gerrit where code review can be done. In our example, the URL for code review is displayed Message Details box.

GitContributionStep6.06.gerrit.url.for.code.review.png

This URL can be opened in a browser. The Sandbox Hudson will verify the supplied changes and set the verified flag if the build was successful.

GitContributionStep6.07.gerrit.in.browser.png

After reviewing the code, the changes can be merged into the feature branch by clicking on the button Review and setting Code-Review +2 and IP-Clean to +1 and pressing Publish and Submit.

GitContributionStep6.08.gerrit.publish.and.submit.png

Switch back to EGit, right-click on the Scout RT Git repository and select Fetch from Upstream.

GitContributionStep6.09.fetch.from.upstream.png

All branches will be fetched, i.e. our remote feature branch should be updated and be visible in the Commit History (Note: For the sake of simplicity we removed all irrelevant branches from the remote tracking folder). Currently, the local feature branch and the remote feature branch point to different commits, however they both contain the same changes. Therefore, we are going to rebase our local feature branch on top of the remote feature branch. Right-click on the remote feature branch and select Rebase on Top of.

GitContributionStep6.10.rebase.png

The local feature branch and remote should now point to the same commit ID.

GitContributionStep6.11.after.rebase.png

Apply commits from feature branch to develop

Before we apply our changes from the feature branch to the develop branch (currently the Scout Luna branch), we decide to make some further changes, commit them into the local feature branch and push them to Gerrit again (please repeat step 6). The new changes for our example are available here. As before, we review and apply these changes into the remote feature branch resulting the Commit History view to display something like this:

GitContributionStep7.01.commit.history.png

We now have two commits in our feature branch (remote and local) and both of them will be applied to to the origin/develop branch as 1 commit, i.e. in the Git context we squash our 2 commits from the feature branch into 1. To achieve this goal we reset our local feature branch luna_target_bug412011 to the remote origin/develop branch by right-clicking and select Reset -> Mixed (HEAD and Index).

GitContributionStep7.02.reset.mixed.png

Reset-Mixed means that the changes from the feature branch will be made available as Unstaged Changes. In the Git Staging perspective we move the changes to the Staged Changes area and commit them locally.

GitContributionStep7.03.squash.commit.png

The Commit History looks like:

GitContributionStep7.04.commit.history.after.commit.png

The local feature branch luna_target_bug412011 is now 1 commit ahead of the origin/develop branch, so we push this commit to Gerrit as follows: Select Push to Gerrit... and configure the dialog like this:

GitContributionStep7.05.push.to.gerrit.develop.branch.png

Hit Ctrl+Space in the Gerrit Branch field and choose develop branch, select refs/for/ in the drop-down field. After a successful code review at Gerrit, we apply this change into the remote develop branch.

After fetching the remote branches the Commit History should now display a new commit on the origin/develop branch.

GitContributionStep7.06.commit.history.after.merging.png

Apply commit from develop to release branch

Assume that the changes from the previous feature branch should also be applied to a release branch, e.g. release/3.9.1. Since we squashed our feature branch commits into the develop branch, we can just cherry pick that commit from the develop branch.

To do this checkout origin/release/3.9.1 to a local branch by right-clicking on the origin/release/3.9.1 and select Create Branch...

GitContributionStep8.01.checkout.release.branch.png

The local branch will be named release/3.9.1.

GitContributionStep8.02.checkout.release.branch.dialog.png

Press Finish and a new local branch should be visible and active.

GitContributionStep8.03.new.local.branch.png

We will now pick the commit from origin/develop that we would also like to have in our release branch 3.9.1. Right-click on the commit f3ea51c and select Cherry Pick.

GitContributionStep8.04.cherrypick.png

The changes are automatically applied and committed to the local release branch.

GitContributionStep8.05.commit.history.after.cherrypick.png

As explained in step 7, we can push these changes to Gerrit. Right-click on the Scout RT Git repository and select Push to Gerrit... Enter release/3.9.1 in the Gerrit Branch field ans select refs/for/ as before.

GitContributionStep8.06.push.to.gerrit.release.branch.png

Press Finish and follow the same procedure as described in step 7 for applying the changes in Gerrit to the remote release branch. Note: We abandon the change since this feature is only intended for Scout 3.10 and not for the release branch 3.9.1. However, the main message how to apply changes from the develop to a release branch should be clear.

Back to the top