|
|
| (125 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| − | = Setting-up Eclipse =
| + | See [[Scout/Contribution/Setup]] and [[Scout/Contribution/Git_Workflows]]. |
| − | 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 [http://git.eclipse.org/c/scout/org.eclipse.scout.rt.git/ 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.
| + | |
| − | | + | |
| − | [[Image:GitContribution.01.select.git.perspective.png|250px]] | + | |
| − | [[Image:GitContribution.02.clone.git.perspective.png|450px]]
| + | |
| − | | + | |
| − | For the [http://git.eclipse.org/c/scout/org.eclipse.scout.rt.git/ Scout RT repository] we use the SSH URL ssh://git.eclipse.org/gitroot/scout/org.eclipse.scout.rt.git. SSH URL is listed under Clone on the webpage of the repository: http://git.eclipse.org/c/scout/org.eclipse.scout.rt.git/. Please fill in your Eclipse Scout committer credentials in the Username and Password field. Since we are interested in the develop and release/3.9.1 (Kepler SR1) branches, we only select these two branches.
| + | |
| − | | + | |
| − | [[Image:GitContribution.03.enter.url.and.credentials.png|400px]]
| + | |
| − | [[Image:GitContribution.04.select.remote.branches.png|400px]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:GitContribution.05.choose.local.destination.png|400px]] | + | |
| − | [[Image:GitContribution.06.cloning.repository.png|400px]]
| + | |
| − | | + | |
| − | === Gerrit Push 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.
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | In the previous step we cloned our Scout RT repository from read-only URL ssh://git.eclipse.org/gitroot/scout/org.eclipse.scout.rt.git. 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.
| + | |
| − | Expand the ''Remotes'' directory, right-click on ''origin'' and select ''Gerrit Configuration...''
| + | |
| − | | + | |
| − | [[Image:GitContributionStep4.01.configure.push.url.png|200px]]
| + | |
| − | | + | |
| − | For Scout RT, we add the URL ''ssh://[username]@git.eclipse.org:29418/scout/org.eclipse.scout.rt.git'' where [username] should be replaced with your committer ID.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep4.02.add.gerrit.png|200px]]
| + | |
| − |
| + | |
| − | Click on ''Finish''. Your Push URL should now look similar like
| + | |
| − | | + | |
| − | [[Image:GitContributionStep4.03.gerrit.added.png|200px]]
| + | |
| − | | + | |
| − | == Import Plugins 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep2.01.import.into.workspace.png|400px]]
| + | |
| − | [[Image:GitContributionStep2.02.import.into.workspace.wizard.png|350px]]
| + | |
| − | [[Image:GitContributionStep2.03.select.plugins.png|350px]]
| + | |
| − | | + | |
| − | = Contributing a patch or feature =
| + | |
| − | Contributing a patch or a new feature to Eclipse Scout Kepler or Luna is done by creating a new feature branch that will be applied to the corresponding develop (currently Luna) or release branch (release/3.9.1 is Kepler SR1). In this chapter all necessary steps are shown to contribute a patch or a feature.
| + | |
| − | This example requires a working EGit installation in the Eclipse IDE.
| + | |
| − | | + | |
| − | == Create a local feature branch ==
| + | |
| − | | + | |
| − | For every new feature a separate branch is created.
| + | |
| − | Assume we want to provide an implementation for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=412011 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep3.01.show.history.png|200px]]
| + | |
| − | | + | |
| − | The History view should be opened and it should look something like
| + | |
| − | | + | |
| − | [[Image:GitContributionStep3.02.history.timeline.png|200px]]
| + | |
| − | | + | |
| − | 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...''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep3.03.create.branch.png|200px]]
| + | |
| − | | + | |
| − | 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep3.03.create.new.feature.branch.png|200px]]
| + | |
| − | | + | |
| − | Click on ''Finish''. The feature branch should now be created locally.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep3.03.feature.branch.created.png|200px]]
| + | |
| − | | + | |
| − | 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...''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep5.01.push.feature.branch.to.remote.png|200px]]
| + | |
| − | | + | |
| − | Select the remote repository which corresponds to the Gerrit Push URL we've just added in the previous step. Press ''Next''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep5.02.select.remote.repository.png|200px]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep5.03.choose.target.ref.name.png|200px]]
| + | |
| − | | + | |
| − | Press ''Finish'' and the feature branch should now be pushed onto the remote repository.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep5.04.feature.branch.pushed.png|200px]]
| + | |
| − | | + | |
| − | The feature branch is visible in the ''Remote Tracking'' directory.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep5.05.feature.branch.added.png|200px]]
| + | |
| − | | + | |
| − | == Commit changes to local feature branch and push to remote repository ==
| + | |
| − | | + | |
| − | In our example we made some initial changes for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=412011 bug 412011] and are now about to commit a new file into the local branch. Switch to the view ''Git Staging''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.01.commit.to.local.branch.png|200px]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.02.stage.and.enter.commit.message.png|200px]]
| + | |
| − | | + | |
| − | 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.03.commit.history.png|200px]]
| + | |
| − | | + | |
| − | 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...''
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.04.push.to.gerrit.png|200px]]
| + | |
| − | | + | |
| − | 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.05.push.to.gerrit.dialog.png|200px]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.06.gerrit.url.for.code.review.png|200px]]
| + | |
| − | | + | |
| − | This [https://git.eclipse.org/r/14180 URL] can be opened in a browser. The [https://hudson.eclipse.org/sandbox/ Sandbox Hudson] will verify the supplied changes and set the ''verified'' flag if the build was successful.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.07.gerrit.in.browser.png|200px]]
| + | |
| − | | + | |
| − | 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.08.gerrit.publish.and.submit.png|200px]]
| + | |
| − | | + | |
| − | Switch back to EGit, right-click on the Scout RT Git repository and select ''Fetch from Upstream''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.09.fetch.from.upstream.png|200px]]
| + | |
| − | | + | |
| − | 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.10.rebase.png|200px]]
| + | |
| − | | + | |
| − | The local feature branch and remote should now point to the same commit ID.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep6.11.after.rebase.png|200px]]
| + | |
| − | | + | |
| − | == 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 [https://git.eclipse.org/r/14182 here]. As before, we review and apply these changes into the remote feature branch resulting the Commit History view to display something like this:
| + | |
| − | | + | |
| − | [[Image:GitContributionStep7.01.commit.history.png|200px]]
| + | |
| − | | + | |
| − | 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)''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep7.02.reset.mixed.png|200px]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep7.03.squash.commit.png|200px]]
| + | |
| − | | + | |
| − | The Commit History looks like:
| + | |
| − | | + | |
| − | [[Image:GitContributionStep7.04.commit.history.after.commit.png|200px]]
| + | |
| − | | + | |
| − | 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:
| + | |
| − | | + | |
| − | [[Image:GitContributionStep7.05.push.to.gerrit.develop.branch.png|200px]]
| + | |
| − | | + | |
| − | 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 [https://git.eclipse.org/r/14189/ 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep7.06.commit.history.after.merging.png|200px]]
| + | |
| − | | + | |
| − | == 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...''
| + | |
| − | | + | |
| − | [[Image:GitContributionStep8.01.checkout.release.branch.png|200px]]
| + | |
| − | | + | |
| − | The local branch will be named ''release/3.9.1''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep8.02.checkout.release.branch.dialog.png|200px]]
| + | |
| − | | + | |
| − | Press ''Finish'' and a new local branch should be visible and active.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep8.03.new.local.branch.png|200px]]
| + | |
| − | | + | |
| − | 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''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep8.04.cherrypick.png|200px]]
| + | |
| − | | + | |
| − | The changes are automatically applied and committed to the local release branch.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep8.05.commit.history.after.cherrypick.png|200px]]
| + | |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep8.06.push.to.gerrit.release.branch.png|200px]]
| + | |
| − | | + | |
| − | 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 [https://git.eclipse.org/r/14193 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.
| + | |
