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.
Difference between revisions of "Orion/Contributing Code"
m |
|||
| (25 intermediate revisions by 5 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. |
| − | == | + | == 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.'' | ||
| + | |||
| + | If you're interesting in contributing to Orion and either just 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 (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. | ||
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 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. | 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 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. | + | 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 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]] | ||
| + | |||
| + | === Clone your GitHub repository === | ||
| + | |||
| + | The next step is to clone your newly-created repository 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 as described [http://wiki.eclipse.org/Orion/How_Tos/Cloning_repository_from_github here]. 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 now load the retrieved project(s) from your cloned repository into your workspace. But 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. | ||
| + | |||
| + | For more info on developing Orion see the [http://wiki.eclipse.org/Orion Development Resources] section. | ||
| + | |||
| + | === Commit your changes === | ||
| + | |||
| + | When your changes are ready for submission, you first commit them to your cloned Git repository (in your newly-created branch). Having done this, the next step is to ensure that your changes are up to date with the ongoing development in the master branch. The best way to do this is to rebase your commits on top of the latest code from the Orion repository. If you are not familiar with rebasing or merging in git, please consult a git user guide, such as [http://progit.org/ Pro Git]. 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 more detailed information on using Orion's Git facilities see the [http://wiki.eclipse.org/Orion/Documentation/User_Guide Orion User Guide]. | ||
| + | |||
| + | === Request adoption of your changes === | ||
| + | |||
| + | Finally, 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 | ||
| + | * 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]] | ||
| + | |||
| + | 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. | ||
| + | |||
| + | == 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. | ||
| − | + | [[Category:Orion|Contributing Code]] | |
Revision as of 10:55, 10 July 2012
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.
Contents
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.
If you're interesting in contributing to Orion and either just 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 (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.
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 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 initially contain the latest Orion code in their "master" branch, and will eventually receive your code changes for submission.
Clone your GitHub repository
The next step is to clone your newly-created repository 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 as described here. 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 now load the retrieved project(s) from your cloned repository into your workspace. But 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.
For more info on developing Orion see the Development Resources section.
Commit your changes
When your changes are ready for submission, you first commit them to your cloned Git repository (in your newly-created branch). Having done this, the next step is to ensure that your changes are up to date with the ongoing development in the master branch. The best way to do this is to rebase your commits on top of the latest code from the Orion repository. If you are not familiar with rebasing or merging in git, please consult a git user guide, such as Pro Git. 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 more detailed information on using Orion's Git facilities see the Orion User Guide.
Request adoption of your changes
Finally, 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
- 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.
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.
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
- 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 git@github.com:someusername/orion.client.git
- 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.