Difference between revisions of "Recommenders/ContributorGuide"
|Line 155:||Line 155:|
Revision as of 04:54, 27 January 2012
- 1 Get in Contact
- 2 Reporting Bugs
- 3 Contributing Patches
- 4 Common Guidelines
Get in Contact
Code Recommenders user forum is here: http://eclipse.org/forums/eclipse.recommenders. If you want to report an issue, request new features, or just get in contact with the development team, this is the preferred way.
Code Recommenders also maintains a developer mailing list. The email@example.com list is used for announcements like committer election or notifying committers about build changes etc. Subscription is required to post messages to the list which can be done here: https://dev.eclipse.org/mailman/listinfo/recommenders-dev.
Code Recommenders' Bugzilla is accessible via https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Recommenders
Shamelessly stolen and adopted from EGit Contributor Guide.
There are just a few things to follow that make contributing simple and fast.
- Create local feature branches.
- Make separate commits for logically separate changes.
- Generate your patch using git tools out of your commits.
- Check the license.
- Review the Eclipse Due Diligence Process.
- Sending your patches.
Each step is described in detail below. If some detail in unclear, let us know.
Create local feature branches
Whenever you create a patch or new feature, just create a new branch as follows:
git branch -b patch-<name>
This creates a new feature branch you can easily work on, synchronize and create patches from later.
Make separate commits for logically separate changes.
- Unless your patch is really trivial, you should not be sending out a patch that was generated between your working tree and your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline.
- In each commit message, describe the technical detail of the change(s).
- If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces.
- Committers in general are very picky about formatting. Make sure your final version of every file was formatted using the Eclipse code formatter using the project specific settings (Properties->Java Code Style->Formatter->"Java Conventions [built-in]").
Generate your patch using git tools out of your commits.
- Git based diff tools (git, and StGIT included) generate unidiff, which is the only acceptable format.
- You do not have to be afraid to use -M option to "git diff" or "git format-patch", if your patch involves file renames. The receiving end can handle them just fine.
- Please make sure your patch does not include any extra files which do not belong in a patch submission.
- Make sure to review your patch after generating it, to ensure accuracy.
- Before sending out, please make sure it cleanly applies to the "master" branch head (i.e., rebase your feature branch with master).
Check the license.
- Code Recommenders is licensed under the Eclipse Public License (EPL).
- Under this licensing model *every* file within the project *must* list which license covers it in the header of the file. Any new contributions to an existing file *must* be submitted under the current license of that file. Any new files *must* clearly indicate which license they are provided under in the file header.
- Please verify that all newly created files have appropriate license header.
- Please verify that you are legally allowed and willing to submit your changes under the license covering each file *prior* to submitting your patch. It is virtually impossible to remove a patch once it has been applied and pushed out.
Review the Eclipse Due Diligence Process.
Sending your patches to Bugzilla.
- "git format-patch" command follows the best current practice to format a commit as a reviewable text message.
- At the beginning of the patch should come your commit message, a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit message starts, you can put a "From: " line to name that person.
- You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" material between the three dash lines and the diffstat, or please place it in the bug description itself.
- If you don't have to add any additional information, this command may be all you need:
git format-patch -M master --stdout > <your-feature-name>.patch
- Then, open a new bug on the Eclipse bug tracker on the EGit project:
- Attach the mailbox file(s) created by "git format-patch" to the bug.
- From here follow the conversation that happens in Bugzilla. You might be asked several times to revise your code, to add tests etc. before you patch finally gets submitted. For an example of this see https://bugs.eclipse.org/bugs/show_bug.cgi?id=290562
Granularity of changes
- Make small commits, as small as reasonable. This makes them easy to review.
- Each commit should have a commit message that explains very clearly what the commit sets out to achieve (unless this is abundantly clear from the code itself, which is basically only the case for trivial patches). Also, when you fix a bug then report which bug you fix. When there are deeper reasons for doing things the way the commit does, then explain these as well. This all is for the reviewers and yourself: the context of the commit is completely clear.
- Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. The purpose of the commit is clear and can be understood easily by the reviewers and yourself.
- Do not break the build and tests for any commit: this is very important for bug hunting.
- Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
- A series of commits should work towards a 'feature' in a clear way and only 'enable' the feature in the last commit of the series.
- In a series of commits first lay the groundwork and then build on that towards the feature.
- Do not mix concerns in branches: when you encounter a bug while working on something then create a new branch to fix the bug. If your work depends on the bug being fixed then rebase your work on that new branch.
- The commit message header should fit on one line and should start with an uppercase letter
- The commit message have newline characters after every 60-70 characters.
- If a Gerrit Change-Id is available (for example when re-submitting to the same change), it should be added in the format below
- If there is an associated bug number in Bugzilla about it, it should come right before Gerrit's Change-Id entry (if available) or towards the end.
- A "Signed-off-by" should be added to the end of the commit message (see example below).
- The first sentence should be a clear and concise description about the change.
- Enter a newline before providing a more detailed description about the change.
Fix the commit dialog to respect the workbench's selection Originally, the commit dialog would automatically check off all files in the dialog. This behaviour contradicts a user's expectation because their selection in the workbench is completely ignored. The code has been corrected to only preselect what the user has actually selected. Bug: 12345 Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a Signed-off-by: Your Name <firstname.lastname@example.org>
Test before submitting
- Run all existing tests. It does not take very long.
Sending patches by mail
Although sending patches by mail is the approved way of interacting with, and asking feedback from, the Code Recommenders project, please don't send patches via git send-email. Instead, please use git format-patch to generate the
mbox, and then attach that to an item in bugzilla as per the above Contributing Patches guides.
If you're sending a work-in-progress for a review, be aware that you can also attach work-in-progress (or RFC) items to Bugzilla; it's not just for finished patches.