Jump to: navigation, search

Difference between revisions of "Recommenders/ContributorGuide"

m
Line 19: Line 19:
 
= Contributing Patches  =
 
= Contributing Patches  =
  
Shamelessly stolen and adopted from [http://egit.eclipse.org/w/?p=egit.git;a=blob_plain;f=SUBMITTING_PATCHES;hb=HEAD EGit Contributor Guide].
+
We welcome patches. We develop software transparently using Eclipse [[Gerrit]]. If you want to contribute a patch.  simply submit it via Gerrit. If you have questions, how to set it up, check the [[Gerrit user guide]] or send an email to the recommenders-dev mailing list.
 
+
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:
+
<pre>git branch -b patch-&lt;name&gt;
+
</pre>
+
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-&gt;Java Code Style-&gt;Formatter-&gt;"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.  ==
+
 
+
*http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf
+
 
+
== 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:
+
<pre> git format-patch -M master --stdout &gt; &lt;your-feature-name&gt;.patch
+
</pre>
+
*Then, open a new bug on the Eclipse bug tracker on the EGit project:
+
 
+
  https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Recommenders
+
 
+
*Attach the mailbox file(s) created by "git format-patch" to the bug.
+
 
+
<br>
+
 
+
*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
+
 
+
= Common Guidelines  =
+
 
+
== 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.
+
 
+
== Commit messages  ==
+
 
+
*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.
+
<pre>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 &lt;your.email@example.org&gt;
+
</pre>
+
== 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 [http://www.kernel.org/pub//software/scm/git/docs/git-send-email.html git send-email]. Instead, please use [http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html git format-patch] to generate the <code>mbox</code>, 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.  
+
  
 
[[Category:Recommenders]]
 
[[Category:Recommenders]]

Revision as of 01:36, 26 September 2013

Get in Contact

Forum

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.

Mailing List

Code Recommenders also maintains a developer mailing list. The recommenders-dev@eclipse.org 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.


Reporting Bugs

Code Recommenders' Bugzilla is accessible via https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Recommenders


Contributing Patches

We welcome patches. We develop software transparently using Eclipse Gerrit. If you want to contribute a patch. simply submit it via Gerrit. If you have questions, how to set it up, check the Gerrit user guide or send an email to the recommenders-dev mailing list.