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

Difference between revisions of "Orion/Contributing Code"

m
m (Commit your changes)
(57 intermediate revisions by 13 users not shown)
Line 1: Line 1:
The Orion project welcomes code contributions from the public.  This page details how to set up a work environment and submit code changes for review and inclusion by a committer.
+
The Orion project welcomes code contributions from the public.  This page details how to set up a work environment and submit code changes for review and inclusion by a committer.  It also describes the process for accepting these changes if you are a committer.
  
== Identify an opportunity ==
+
== For contributors ==
  
Bug fixes are the most common type of code contribution. For a list of currently-open Orion bugs see the [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;product=Orion;classification=Eclipse Eclipse Bugzilla database].  If a bug's Assignee is an "inbox" name (eg.- "orion.client-inbox@eclipse.org") then it has not been assigned to anyone yet, and is a good candidate for investigation.  If you plan to fix a bug in Orion that does not already have a bug report then be sure to first log a report, and in the initial comment specify that you are investigating a fix for it.  This report should be logged up-front so that if the bug is not one that should be fixed (for example, it is actually working as designed, its component is in the midst of a re-write, etc.), then a committer can add a follow-up comment indicating that the bug is not worth investigating.
+
Welcome!  Thanks for helping us out.  We have an understood method for earning your commit rights to the Orion code base.  Our overall description is as follows:
 +
 
 +
''Potential committers must have at least 5 reasonable commits, reviewed by 3 different existing committers, over a minimum of 6 weeks of contributions. A review of potential committers will be carried out at the end of each Milestone and at the end of the current release cycle.''
 +
 
 +
Even if you don't become a full-blown committer, you can always contribute on a case-by-case basis, whether by fixing a few bugs or helping us drive the technology forward by focusing on a particular component. Here are the basic steps for finding the most common type of contribution.
 +
 
 +
=== Identify an opportunity ===
 +
 
 +
For a list of currently-open Orion bugs see the [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;product=Orion;classification=Eclipse Eclipse Bugzilla database].  If a bug's Assignee is an "inbox" name (e.g. "orion.client-inbox@eclipse.org") then it has not been assigned to anyone yet, and is a good candidate for investigation.  If you plan to fix a bug in Orion that does not already have a bug report then be sure to first log a report, and in the initial comment specify that you are investigating a fix for it.  This report should be logged up-front so that if the bug is not one that should be fixed (for example, it is actually working as designed, its component is in the midst of a re-write, etc.), then a committer can add a follow-up comment indicating that the bug is not worth investigating.
  
 
New features/enhancements can also be contributed, but for these it is important that a committer comment in its bug report indicate that the feature is desirable.  The potential for feature work in any project is limitless, but not all features are good fits, so a feature that was not pre-approved by a committer risks not being ultimately accepted.
 
New features/enhancements can also be contributed, but for these it is important that a committer comment in its bug report indicate that the feature is desirable.  The potential for feature work in any project is limitless, but not all features are good fits, so a feature that was not pre-approved by a committer risks not being ultimately accepted.
  
== Set up a Git repository ==
+
=== Set up a Git repository ===
 +
 
 +
The first step is to establish a Git repository.  The remainder of this page assumes that [http://github.com GitHub] is being used to host your repository, since it is a well-established Git hosting service and the Orion repository is mirrored there.  However using GitHub is not a strict requirement.
 +
 
 +
Once you are logged in to your user account on GitHub, start by navigating to and then creating forks of the https://github.com/eclipse/orion.client and/or https://github.com/eclipse/orion.server repositories.  These repositories will initially contain the latest Orion code in their "master" branch, and will eventually receive your code changes for submission.
 +
<br><br>[[Image:github-fork.jpg|Github Fork Screenshot]]
 +
 
 +
You should also update your GitHub profile with your picture by using an avatar from gravatar.com. All your commits in the UI will contain your user image and you do not want to see a gray GitHub octocat mascot image in it's place.
 +
 
 +
=== Clone your GitHub repository ===
 +
 
 +
The next step is to clone your newly-created GitHub repositories into your work environment.  For example, if you are planning to use Orion to develop Orion client-side code then you will [http://wiki.eclipse.org/Orion/How_Tos/Cloning_repository_from_github clone the GitHub repository].  Alternatively, if you will be developing Orion server-side code then you will likely use Eclipse as your development environment, and either EGit or command-line Git for cloning your GitHub repository locally.
 +
 
 +
You can follow [http://wiki.eclipse.org/Orion/Getting_the_source#Clone_the_client_and_server_Git_repositories_into_Eclipse Clone the client and server Git repositories into Eclipse]
 +
 
 +
From the command line:
 +
<pre>
 +
% git clone https://github.com/username/orion.client.git
 +
% git clone https://github.com/username/orion.server.git
 +
</pre>
 +
 
 +
You can now load the retrieved project(s) from your cloned repository into your workspace.
 +
 
 +
=== Create a branch for your work ===
 +
 
 +
Before you begin hacking, be sure to create a new branch for your work on this particular task. This branch is where you will ultimately make your changes available from.
 +
 
 +
To create and switch to the branch in Orion, there is a <b>New Branch</b> link on the Git Repositories page. In Eclipse, select a project, right click and select Team > Switch To > New Branch.
 +
 
 +
From the command line:
 +
<pre>
 +
% git branch <name_of_your_new_branch>
 +
% git checkout <name_of_your_new_branch>
 +
</pre>
 +
 
 +
If you miss this step and start committing changes on the master branch, see [http://wiki.eclipse.org/Orion/Contributing_Code#Strange_commit:_Merge_remote-tracking_branch_.27upstream.2Fmaster.27 Strange commit: Merge remote-tracking branch 'upstream/master']
 +
 
 +
=== Sign the Eclipse CLA ===
 +
If you have not done it already, you must:
 +
# [https://dev.eclipse.org/site_login/?takemeback=https://projects.eclipse.org/user/login/sso Create an account] at Eclipse.org.
 +
# [https://projects.eclipse.org/user/login/sso Log in], and sign the Contributor License Agreement (CLA) form.
 +
The CLA must be signed before we can accept your contribution. But on the bright side, this only has to be done once.
 +
 
 +
=== Commit your changes ===
 +
 
 +
When your changes are ready for submission, you first commit them to your cloned Git repository in your branch. Your commit message should include the bug number and title at the beginning and  must include a signoff line at the end, which looks like this:
 +
 
 +
<pre>
 +
Bug 439556 - nonnlsPlugin only does half the job
 +
 
 +
... any comments or descriptions about this change
 +
... any comments or descriptions about this change
 +
 
 +
Signed-off-by: Your Name <your_email@whatever.com>
 +
</pre>
 +
 
 +
 
 +
The signoff line, and the Git Author field, must use the '''same email address''' as your Eclipse account.
 +
 
 +
Having done this, it's also a good idea to ensure that your changes are up to date with the ongoing development in the master branch. See [http://wiki.eclipse.org/Orion/Contributing_Code#Keeping_up_to_date Keeping up to date] for information. Once your commit is up to date on the latest code and the fix is retested, then please push the commit to your GitHub repository.  For detailed information on using Orion's Git facilities see the [http://wiki.eclipse.org/Orion/Documentation/User_Guide Orion User Guide].
 +
 
 +
=== Submit your changes to Gerrit ===
 +
The best way to get your changes into Orion is by submitting them to [https://wiki.eclipse.org/Gerrit Gerrit].
 +
 
 +
# Set up Gerrit using the instructions here: [[Orion/How_Tos/Using_Gerrit_in_Orion#Configure_the_Gerrit_remote_.28Option_2.29|Configure the Gerrit remote]]
 +
# At this point you should have a <tt>gerrit</tt> remote.
 +
# Push your changes to the gerrit remote.
 +
# This should create a review in Gerrit.
 +
# If you're fixing a bug, add a comment to the bug and link to your Gerrit review (this will help get people's attention).
 +
 
 +
It will then be up to a committer to review your change, ask questions, suggest improvements, etc.  Once the change is deemed to be ready then the committer can add it to the Orion repository.
 +
 
 +
=== Submit your changes through GitHub (optional) ===
 +
If you can't get Gerrit to work, you can just post a link to your code on GitHub. Add a comment to the Orion bug report indicating that you have changes that you want to submit, and provide the following:
 +
* the URL of your GitHub repository (read-only access is fine)
 +
* the name of the branch containing your changes
 +
* the commit id of the commit in the branch. You should paste the actual link of the URL of the commit from your commit log. You can find this link easiest in either Orion or on GitHib directly.
 +
* set the "review" flag to "?". Optionally you can enter the email address of a particular committer you would like to have review the change. If you don't know or care, just leave the email address blank.
 +
 
 +
[[Image:Bugzilla-Review-Flag.png|Bugzilla Review Flag Screenshot]]
 +
 
 +
== For Orion Committers ==
 +
 
 +
=== Finding bugs to review ===
 +
 
 +
You can locate all bugs awaiting review with the following [http://tinyurl.com/orion-waiting-contributions bugzilla query]. Edit this query to narrow down to specific contributors, dates, etc.
 +
 
 +
Hopefully this will get simpler in the future.
 +
 
 +
=== Accepting a contribution ===
 +
 
 +
# Open the Orion Repositories page on the orion repo (client or server) that is appropriate.
 +
# Scroll down to the '''Remotes''' section of the page and push the plus sign icon on the right of the section heading to add a remote.
 +
# Copy the URL of the GitHub repository provided by the committer.  It will look something like <tt>git@github.com:someusername/orion.client.git</tt>
 +
# Push the "Fetch" button to retrieve the branches from the remote
 +
# Scroll back up to the '''Branches''' section of the page and click on the link that says '''See all branches'''  (See {{bug|369297}} as this is evolving...)
 +
# Open the '''Git Log''' page on that branch and find the commit you are looking for.
 +
# Click on the commit link to open a commit page and browse the diffs. 
 +
## If you don't like the proposed fix, communicate with the contributor in the bug, and start over when a new commit is proposed.
 +
## If the fix looks acceptable, you can cherry pick the commit, which will apply the commit to your active branch.  Then you can run the code and test it all.  IMPORTANT:  It's a good idea to make a topic branch in git for your work.  That way you won't have polluted your master branch if you decide not to push the fix.
 +
# Open the Git Log view on your active branch and verify that the contributor's commit(s) are present.
 +
# Test the fix.
 +
# If you are ready to commit, verify that the contributor's name appears in the "Author" field. (Your name should appear in the "Committer" field.)
 +
# Merge into your master branch.
 +
# Push.
 +
# Thank the contributor. :)
 +
# Make suggestions in {{bug|369591}} (or better yet, try to fix it) for how this could be better.
 +
 
 +
=== Variation 1: accepting a contribution from git hub pull request===
 +
This variation assumes that the contributor follows all the contributors steps but only sent out the pull request.
 +
 
 +
# From the pull request, find the commit id.
 +
# Use this format of URL : <b>YourOrionServer</b>/git/reviewRequest.html#https://github.com/<b>contributorId</b>/orion.client.git_<b>contributorCommitId</b> and paste it in a browser. If it is a server code contribution, change the <b>orion.client.git</b> part to orion.server.git.
 +
# Now you are in the Orion review request page. Expand the <b>Attach the remote to one of your existing repositories</b> section.
 +
# Find your Orion repository and use <b>Add a new remote to your repository</b> command on the right hand side.
 +
# Now you will see a new section <b>The commit can be found in the following repositories</b>. Expand it and you will see the contributor's commit is there.
 +
# Use the <b>Open Commit</b> link on the right hand side, which brings you to the git commit page.
 +
# Review and compare the changes. If the code is OK, then use the <b>Cherry-Pick</b> command to pick it up in your active branch.
 +
# Go to git status page and push it into your Orion remote repository.
 +
# In the future when {{bug|395824}} is fixed, the above steps will be simpler.
 +
 
 +
== Git tips ==
 +
 
 +
=== Keeping up to date ===
 +
 
 +
From time to time you will want to synchronize your forked repositories with the latest changes in the repositories at Eclipse.org. To do this, we need to add a remote that points to the upstream repository.
 +
 
 +
In Orion, you can add a remote to each clone using the button on the repositories page.
 +
 
 +
In Eclipse, each clone in the Git Repositories view has a list of remotes and you can add a remote by right clicking there.
 +
 
 +
From the command line:
 +
<pre>
 +
% git remote add upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git
 +
% git remote add upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git
 +
</pre>
 +
Once complete, to verify you should see:
 +
<pre>
 +
% cd ../orion.server/
 +
% git remote -v
 +
origin https://github.com/ahunter-orion/orion.server.git (fetch)
 +
origin https://github.com/ahunter-orion/orion.server.git (push)
 +
upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git (fetch)
 +
upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git (push)
 +
% cd ../orion.client/
 +
% git remote -v
 +
origin https://github.com/ahunter-orion/orion.client.git (fetch)
 +
origin https://github.com/ahunter-orion/orion.client.git (push)
 +
upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git (fetch)
 +
upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git (push)
 +
</pre>
 +
 
 +
You can now bring in the latest changes. Using the command line:
 +
First make sure we are on the master branch:
 +
<pre>
 +
% git checkout master
 +
Switched to branch 'master'
 +
</pre>
 +
Bring in the latest changes from both remotes:
 +
<pre>
 +
% git fetch
 +
% git fetch upstream
 +
</pre>
 +
Alternatively:
 +
<pre>
 +
% git remote update -p
 +
</pre>
 +
Then merge into your local branch:
 +
<pre>
 +
git merge upstream/master
 +
</pre>
 +
You can them push the changes to GitHub:
 +
<pre>
 +
git push
 +
</pre>
 +
 
 +
Similarly from Orion and Eclipse the above fetch, merge and push commands are available on the repositories page in Orion and from the Team menu when selecting a project in Eclipse.
 +
 
 +
=== Strange commit: Merge remote-tracking branch 'upstream/master' ===
 +
 
 +
Suppose you have your clone of a repository on GitHub and you pushed changes to master rather than working in a branch. Subsequently, when you push to your clone, you will see in your commits log:
 +
<pre>
 +
Merge remote-tracking branch 'upstream/master'
 +
</pre>
 +
Git is downloading the other developer's commits and then merging them into your local branch.
 +
 
 +
This merge does not break anything, but it is desirable to have a clean master branch with only commits from the original repository and a clean commit log.
 +
 
 +
To fix, you can move any old commits to a new branch and then restore your master branch to be exactly the same as upstream/master:
 +
 
 +
Create a new branch containing all your work currently in master:
 +
<pre>
 +
% git branch my-work-done master
 +
</pre>
  
The first step is to establish a Git repository.  The remainder of this page assumes that GitHub is being used to host your repository, since it is a well-established Git hosting service and the Orion repository is mirrored there.  However using GitHub is not a strict requirement.
+
Then reset master to upstream's view:
 +
<pre>
 +
% git reset --hard origin/master
 +
</pre>
  
Once you have a user account on GitHub, start by creating forks of the https://github.com/eclipse/orion.client and/or https://github.com/eclipse/orion.server repositories.  These repositories will contain the latest Orion code in their "master" branch, and will eventually receive your code changes for submission.
+
==== Using <code>rebase</code>, Git's expert mode ====
 +
The Git <code>rebase</code> command can help you develop against a shared branch (like <code>master</code>), and keep your local branch up to date with other developers' changes, '''and''' avoid unpleasant merge commits. Rebase does it all.
  
== Clone your repository ==
+
Assume you have some commits in your local master branch that you haven't pushed yet, and you want to bring in changes from upstream. Do this:
 +
% git fetch upstream
 +
% git rebase upstream/master
  
The next step is to clone your newly-created repository into your Orion environment, which is described in detail [http://wiki.eclipse.org/Orion/How_Tos/Cloning_repository_from_github here].  Once this is complete the orion.client and/or orion.server projects will be created in your Orion workspace, and are ready for hacking.
+
Effectively, rebase will set aside any commits you have in your local copy of <code>master</code>, then reset master to upstream's master, then re-apply your commits on top.
  
== Commit your changes ==
+
You can even do this all in a single command:
 +
% git pull --rebase origin master
  
Once your changes are ready for submission, you first commit them to the Git repository in your Orion environment, and then push this repository to your Git repository on GitHub. For more detailed information on using Orion's Git facilities see the [http://wiki.eclipse.org/Orion/Documentation/User_Guide Orion User Guide].
+
("pull" is the equivalent of fetch followed by merge. "pull --rebase" is the equivalent of fetch followed by rebase.)
  
== Request adoption of your changes ==
+
If a rebase runs into trouble, you can usually unroll the entire operation by doing
 +
% git rebase --abort
  
Finally, on GitHub create a Pull Request for your changes, which creates a page similar to [https://github.com/eclipse/orion.client/pull/9 https://github.com/eclipse/orion.client/pull/9].  Paste this Pull Request link into a comment in the Orion bug report and add "patch" to its Keyword field.  It will then be up to a committer to review your change, ask questions, suggest improvements, etc.  Once the change is deemed to be ready then the committer can add it to the Orion repository.
+
[[Category:Orion|Contributing Code]]
 +
[[Category:How to Contribute]]

Revision as of 09:42, 20 January 2015

The Orion project welcomes code contributions from the public. This page details how to set up a work environment and submit code changes for review and inclusion by a committer. It also describes the process for accepting these changes if you are a committer.

For contributors

Welcome! Thanks for helping us out. We have an understood method for earning your commit rights to the Orion code base. Our overall description is as follows:

Potential committers must have at least 5 reasonable commits, reviewed by 3 different existing committers, over a minimum of 6 weeks of contributions. A review of potential committers will be carried out at the end of each Milestone and at the end of the current release cycle.

Even if you don't become a full-blown committer, you can always contribute on a case-by-case basis, whether by fixing a few bugs or helping us drive the technology forward by focusing on a particular component. Here are the basic steps for finding the most common type of contribution.

Identify an opportunity

For a list of currently-open Orion bugs see the Eclipse Bugzilla database. If a bug's Assignee is an "inbox" name (e.g. "orion.client-inbox@eclipse.org") then it has not been assigned to anyone yet, and is a good candidate for investigation. If you plan to fix a bug in Orion that does not already have a bug report then be sure to first log a report, and in the initial comment specify that you are investigating a fix for it. This report should be logged up-front so that if the bug is not one that should be fixed (for example, it is actually working as designed, its component is in the midst of a re-write, etc.), then a committer can add a follow-up comment indicating that the bug is not worth investigating.

New features/enhancements can also be contributed, but for these it is important that a committer comment in its bug report indicate that the feature is desirable. The potential for feature work in any project is limitless, but not all features are good fits, so a feature that was not pre-approved by a committer risks not being ultimately accepted.

Set up a Git repository

The first step is to establish a Git repository. The remainder of this page assumes that GitHub is being used to host your repository, since it is a well-established Git hosting service and the Orion repository is mirrored there. However using GitHub is not a strict requirement.

Once you are logged in to your user account on GitHub, start by navigating to and then creating forks of the https://github.com/eclipse/orion.client and/or https://github.com/eclipse/orion.server repositories. These repositories will initially contain the latest Orion code in their "master" branch, and will eventually receive your code changes for submission.

Github Fork Screenshot

You should also update your GitHub profile with your picture by using an avatar from gravatar.com. All your commits in the UI will contain your user image and you do not want to see a gray GitHub octocat mascot image in it's place.

Clone your GitHub repository

The next step is to clone your newly-created GitHub repositories into your work environment. For example, if you are planning to use Orion to develop Orion client-side code then you will clone the GitHub repository. Alternatively, if you will be developing Orion server-side code then you will likely use Eclipse as your development environment, and either EGit or command-line Git for cloning your GitHub repository locally.

You can follow Clone the client and server Git repositories into Eclipse

From the command line:

% git clone https://github.com/username/orion.client.git
% git clone https://github.com/username/orion.server.git

You can now load the retrieved project(s) from your cloned repository into your workspace.

Create a branch for your work

Before you begin hacking, be sure to create a new branch for your work on this particular task. This branch is where you will ultimately make your changes available from.

To create and switch to the branch in Orion, there is a New Branch link on the Git Repositories page. In Eclipse, select a project, right click and select Team > Switch To > New Branch.

From the command line:

% git branch <name_of_your_new_branch>
% git checkout <name_of_your_new_branch>

If you miss this step and start committing changes on the master branch, see Strange commit: Merge remote-tracking branch 'upstream/master'

Sign the Eclipse CLA

If you have not done it already, you must:

  1. Create an account at Eclipse.org.
  2. Log in, and sign the Contributor License Agreement (CLA) form.

The CLA must be signed before we can accept your contribution. But on the bright side, this only has to be done once.

Commit your changes

When your changes are ready for submission, you first commit them to your cloned Git repository in your branch. Your commit message should include the bug number and title at the beginning and must include a signoff line at the end, which looks like this:

Bug 439556 - nonnlsPlugin only does half the job

... any comments or descriptions about this change
... any comments or descriptions about this change

Signed-off-by: Your Name <your_email@whatever.com>


The signoff line, and the Git Author field, must use the same email address as your Eclipse account.

Having done this, it's also a good idea to ensure that your changes are up to date with the ongoing development in the master branch. See Keeping up to date for information. Once your commit is up to date on the latest code and the fix is retested, then please push the commit to your GitHub repository. For detailed information on using Orion's Git facilities see the Orion User Guide.

Submit your changes to Gerrit

The best way to get your changes into Orion is by submitting them to Gerrit.

  1. Set up Gerrit using the instructions here: Configure the Gerrit remote
  2. At this point you should have a gerrit remote.
  3. Push your changes to the gerrit remote.
  4. This should create a review in Gerrit.
  5. If you're fixing a bug, add a comment to the bug and link to your Gerrit review (this will help get people's attention).

It will then be up to a committer to review your change, ask questions, suggest improvements, etc. Once the change is deemed to be ready then the committer can add it to the Orion repository.

Submit your changes through GitHub (optional)

If you can't get Gerrit to work, you can just post a link to your code on GitHub. Add a comment to the Orion bug report indicating that you have changes that you want to submit, and provide the following:

  • the URL of your GitHub repository (read-only access is fine)
  • the name of the branch containing your changes
  • the commit id of the commit in the branch. You should paste the actual link of the URL of the commit from your commit log. You can find this link easiest in either Orion or on GitHib directly.
  • set the "review" flag to "?". Optionally you can enter the email address of a particular committer you would like to have review the change. If you don't know or care, just leave the email address blank.

Bugzilla Review Flag Screenshot

For Orion Committers

Finding bugs to review

You can locate all bugs awaiting review with the following bugzilla query. Edit this query to narrow down to specific contributors, dates, etc.

Hopefully this will get simpler in the future.

Accepting a contribution

  1. Open the Orion Repositories page on the orion repo (client or server) that is appropriate.
  2. Scroll down to the Remotes section of the page and push the plus sign icon on the right of the section heading to add a remote.
  3. Copy the URL of the GitHub repository provided by the committer. It will look something like git@github.com:someusername/orion.client.git
  4. Push the "Fetch" button to retrieve the branches from the remote
  5. Scroll back up to the Branches section of the page and click on the link that says See all branches (See bug 369297 as this is evolving...)
  6. Open the Git Log page on that branch and find the commit you are looking for.
  7. Click on the commit link to open a commit page and browse the diffs.
    1. If you don't like the proposed fix, communicate with the contributor in the bug, and start over when a new commit is proposed.
    2. If the fix looks acceptable, you can cherry pick the commit, which will apply the commit to your active branch. Then you can run the code and test it all. IMPORTANT: It's a good idea to make a topic branch in git for your work. That way you won't have polluted your master branch if you decide not to push the fix.
  8. Open the Git Log view on your active branch and verify that the contributor's commit(s) are present.
  9. Test the fix.
  10. If you are ready to commit, verify that the contributor's name appears in the "Author" field. (Your name should appear in the "Committer" field.)
  11. Merge into your master branch.
  12. Push.
  13. Thank the contributor. :)
  14. Make suggestions in bug 369591 (or better yet, try to fix it) for how this could be better.

Variation 1: accepting a contribution from git hub pull request

This variation assumes that the contributor follows all the contributors steps but only sent out the pull request.

  1. From the pull request, find the commit id.
  2. Use this format of URL : YourOrionServer/git/reviewRequest.html#https://github.com/contributorId/orion.client.git_contributorCommitId and paste it in a browser. If it is a server code contribution, change the orion.client.git part to orion.server.git.
  3. Now you are in the Orion review request page. Expand the Attach the remote to one of your existing repositories section.
  4. Find your Orion repository and use Add a new remote to your repository command on the right hand side.
  5. Now you will see a new section The commit can be found in the following repositories. Expand it and you will see the contributor's commit is there.
  6. Use the Open Commit link on the right hand side, which brings you to the git commit page.
  7. Review and compare the changes. If the code is OK, then use the Cherry-Pick command to pick it up in your active branch.
  8. Go to git status page and push it into your Orion remote repository.
  9. In the future when bug 395824 is fixed, the above steps will be simpler.

Git tips

Keeping up to date

From time to time you will want to synchronize your forked repositories with the latest changes in the repositories at Eclipse.org. To do this, we need to add a remote that points to the upstream repository.

In Orion, you can add a remote to each clone using the button on the repositories page.

In Eclipse, each clone in the Git Repositories view has a list of remotes and you can add a remote by right clicking there.

From the command line:

% git remote add upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git
% git remote add upstream http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git

Once complete, to verify you should see:

% cd ../orion.server/
% git remote -v
origin	https://github.com/ahunter-orion/orion.server.git (fetch)
origin	https://github.com/ahunter-orion/orion.server.git (push)
upstream	http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git (fetch)
upstream	http://git.eclipse.org/gitroot/orion/org.eclipse.orion.server.git (push)
% cd ../orion.client/
% git remote -v
origin	https://github.com/ahunter-orion/orion.client.git (fetch)
origin	https://github.com/ahunter-orion/orion.client.git (push)
upstream	http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git (fetch)
upstream	http://git.eclipse.org/gitroot/orion/org.eclipse.orion.client.git (push)

You can now bring in the latest changes. Using the command line: First make sure we are on the master branch:

% git checkout master
Switched to branch 'master'

Bring in the latest changes from both remotes:

% git fetch
% git fetch upstream

Alternatively:

% git remote update -p

Then merge into your local branch:

git merge upstream/master

You can them push the changes to GitHub:

git push

Similarly from Orion and Eclipse the above fetch, merge and push commands are available on the repositories page in Orion and from the Team menu when selecting a project in Eclipse.

Strange commit: Merge remote-tracking branch 'upstream/master'

Suppose you have your clone of a repository on GitHub and you pushed changes to master rather than working in a branch. Subsequently, when you push to your clone, you will see in your commits log:

Merge remote-tracking branch 'upstream/master'

Git is downloading the other developer's commits and then merging them into your local branch.

This merge does not break anything, but it is desirable to have a clean master branch with only commits from the original repository and a clean commit log.

To fix, you can move any old commits to a new branch and then restore your master branch to be exactly the same as upstream/master:

Create a new branch containing all your work currently in master:

% git branch my-work-done master

Then reset master to upstream's view:

% git reset --hard origin/master

Using rebase, Git's expert mode

The Git rebase command can help you develop against a shared branch (like master), and keep your local branch up to date with other developers' changes, and avoid unpleasant merge commits. Rebase does it all.

Assume you have some commits in your local master branch that you haven't pushed yet, and you want to bring in changes from upstream. Do this:

% git fetch upstream
% git rebase upstream/master

Effectively, rebase will set aside any commits you have in your local copy of master, then reset master to upstream's master, then re-apply your commits on top.

You can even do this all in a single command:

% git pull --rebase origin master

("pull" is the equivalent of fetch followed by merge. "pull --rebase" is the equivalent of fetch followed by rebase.)

If a rebase runs into trouble, you can usually unroll the entire operation by doing

% git rebase --abort

Back to the top