Browse Source

Update SUBMITTING_PATCHES

It contained outdated information about attaching patches to bug
reports. Shorten it to the essentials.

Also format it using markdown and rename it to CONTRIBUTING.md, which is
a convention and doesn't include "patches" in the name.

Change-Id: I9ee73f16e6fa8fbf529ac0ca791e2375d4d56d68
Signed-off-by: Robin Stocker <robin@nibor.org>
tags/v3.5.0.201409071800-rc1
Robin Stocker 8 years ago
parent
commit
f3fc379757
2 changed files with 44 additions and 106 deletions
  1. 44
    0
      CONTRIBUTING.md
  2. 0
    106
      SUBMITTING_PATCHES

+ 44
- 0
CONTRIBUTING.md View File

@@ -0,0 +1,44 @@
Contributing
============

Please refer to the contributor guide for all the details:

https://wiki.eclipse.org/EGit/Contributor_Guide


Reporting bugs
--------------

For anything other than small changes, it's a good idea to open a bug
report for it (in case one doesn't already exist). This gives others the
chance to give input and is useful for tracking. Create one here:

https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JGit


Submitting changes
------------------

We use Gerrit to review all changes by committers or contributors before
they are merged:

https://git.eclipse.org/r/

Make sure you have an account and have set up the `commit-msg` hook
before committing.

When committing your changes, see the contributor guide or other commits
on what your commit message should include.

Run the following to push your change for review (with `username`
replaced by your Gerrit username):

git push ssh://username@git.eclipse.org:29418/jgit/jgit.git HEAD:refs/for/master

Add the link to the review as a comment on the bug report, so that
people coming from the bug report can find it.

Then wait for someone to review your change. If there is something to be
corrected, amend your commit and push it again.

Have fun :).

+ 0
- 106
SUBMITTING_PATCHES View File

@@ -1,106 +0,0 @@
Short Version:

- Make small logical changes.
- Provide a meaningful commit message.

- Review and follow the Eclipse Due Diligence Process

http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php
http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf

- Review and follow the current guidelines:

http://wiki.eclipse.org/EGit/Contributor_Guide


Long Version:

I wanted a file describing how to submit patches for JGit,
so I started with the one found in the core Git distribution
(Documentation/SubmittingPatches), which itself was based on the
patch submission guidelines for the Linux kernel.

However there are quite a few differences, so please review and
familiarize yourself with the following relevant bits:


(1) 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.

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.

I am 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]").


(2) 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.


(3) Check the license.

JGit is licensed under the Eclipse Distribution License (EDL,
http://www.eclipse.org/org/documents/edl-v10.html), which is a
renamed version of the new style/3-clause BSD license.

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 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.


(4) Review the Eclipse Due Diligence Process.

http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf


(5) Sending your patches.

"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.

Open a new bug on the Eclipse bug tracker on the EGit project:

https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EGit

Attach the mailbox file(s) created by "git format-patch" to the bug.


Loading…
Cancel
Save