|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366 |
- Short Version:
-
- - Make small logical changes.
- - Provide a meaningful commit message.
-
- - Include your Signed-Off-By line to note you agree with the
- Developer's Certificate of Origin (see below).
- - Make sure all code is under the proper license:
-
- 3-clause BSD
-
- - Use a subject prefix of "[PATCH JGIT ...]" when sending any
- patches directly by email.
-
- - Send by email to the maintainers, cc'ing the git mailing list
- which is currently used for both Git and JGit:
-
- maintainers : "Shawn O. Pearce" <spearce@spearce.org>
- Robin Rosenberg <robin.rosenberg@dewire.com>
-
- git list : git@vger.kernel.org
-
- git list info : http://vger.kernel.org/vger-lists.html#git
-
- 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 some 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) Sending your patches.
-
- People on the git mailing list need to be able to read and comment
- on the changes you are submitting. It is important for a developer
- to be able to "quote" your changes, using standard e-mail tools, so
- that they may comment on specific portions of your code. For this
- reason, all patches should be submitted "inline". WARNING: Be wary
- of your MUAs word-wrap corrupting your patch. Do not cut-n-paste
- your patch; you can lose tabs that way if you are not careful.
-
- It is a common convention to prefix your subject line with [PATCH].
- This lets people easily distinguish patches from other e-mail
- discussions.
-
- "git format-patch" command follows the best current practice to
- format the body of an e-mail message. At the beginning of the patch
- should come your commit message, ending with the Signed-off-by:
- lines, and 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.
-
- Do not attach the patch as a MIME attachment, compressed or not.
- Do not let your e-mail client send quoted-printable. Do not let your
- e-mail client send format=flowed which would destroy whitespaces
- in your patches. Many popular e-mail applications will not always
- transmit a MIME attachment as plain text, making it impossible to
- comment on your code. A MIME attachment also takes a bit more
- time to process. This does not decrease the likelihood of your
- MIME-attached change being accepted, but it makes it more likely
- that it will be postponed.
-
- Exception: If your mailer is mangling patches then someone may ask
- you to re-send them using MIME, that is OK.
-
- Do not PGP sign your patch, at least for now. Most likely, your
- maintainer or other people on the list would not have your PGP
- key and would not bother obtaining it anyway. Your patch is not
- judged by who you are; a good patch from an unknown origin has a
- far better chance of being accepted than a patch from a known,
- respected origin that is done poorly or does incorrect things.
-
- If you really really really really want to do a PGP signed
- patch, format it as "multipart/signed", not a text/plain message
- that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
- not a text/plain, it's something else.
-
- Note that your maintainer does not necessarily read everything
- on the git mailing list. If your patch is for discussion first,
- send it "To:" the mailing list, and optionally "cc:" him. If it
- is trivially correct or after the list reached a consensus, send it
- "To:" the maintainer and optionally "cc:" the list.
-
-
- (4) Check the license
-
- JGit is licensed under the 3-clause (new-style) BSD.
-
- Because of 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.
-
-
- (5) Sign your work
-
- To improve tracking of who did what, we've borrowed the "sign-off"
- procedure from the Linux kernel project on patches that are being
- emailed around. Although JGit is a lot smaller project it is
- a good discipline to follow it.
-
- The sign-off is a simple line at the end of the explanation for the
- patch, which certifies that you wrote it or otherwise have the right
- to pass it on as a open-source patch. The rules are pretty simple:
- if you can certify the below:
-
- Developer's Certificate of Origin 1.1
-
- By making a contribution to this project, I certify that:
-
- (a) The contribution was created in whole or in part by me
- and I have the right to submit it under the open source
- license indicated in the file; or
-
- (b) The contribution is based upon previous work that, to the
- best of my knowledge, is covered under an appropriate
- open source license and I have the right under that
- license to submit that work with modifications, whether
- created in whole or in part by me, under the same open
- source license (unless I am permitted to submit under
- a different license), as indicated in the file; or
-
- (c) The contribution was provided directly to me by some
- other person who certified (a), (b) or (c) and I have
- not modified it.
-
- (d) I understand and agree that this project and the
- contribution are public and that a record of the
- contribution (including all personal information I
- submit with it, including my sign-off) is maintained
- indefinitely and may be redistributed consistent with
- this project or the open source license(s) involved.
-
- then you just add a line saying
-
- Signed-off-by: Random J Developer <random@developer.example.org>
-
- This line can be automatically added by git if you run the git-commit
- command with the -s option.
-
- Some people also put extra tags at the end. They'll just be ignored
- for now, but you can do this to mark internal company procedures
- or just point out some special detail about the sign-off.
-
-
- ------------------------------------------------
- MUA specific hints
-
- Some of patches I receive or pick up from the list share common
- patterns of breakage. Please make sure your MUA is set up
- properly not to corrupt whitespaces. Here are two common ones
- I have seen:
-
- * Empty context lines that do not have _any_ whitespace.
-
- * Non empty context lines that have one extra whitespace at the
- beginning.
-
- One test you could do yourself if your MUA is set up correctly is:
-
- * Send the patch to yourself, exactly the way you would, except
- To: and Cc: lines, which would not contain the list and
- maintainer address.
-
- * Save that patch to a file in UNIX mailbox format. Call it say
- a.patch.
-
- * Try to apply to the tip of the "master" branch from the
- egit.git public repository:
-
- $ git fetch git://repo.or.cz/egit.git master:test-apply
- $ git checkout test-apply
- $ git reset --hard
- $ git am a.patch
-
- If it does not apply correctly, there can be various reasons.
-
- * Your patch itself does not apply cleanly. That is _bad_ but
- does not have much to do with your MUA. Please rebase the
- patch appropriately.
-
- * Your MUA corrupted your patch; applymbox would complain that
- the patch does not apply. Look at .dotest/ subdirectory and
- see what 'patch' file contains and check for the common
- corruption patterns mentioned above.
-
- * While you are at it, check what are in 'info' and
- 'final-commit' files as well. If what is in 'final-commit' is
- not exactly what you would want to see in the commit log
- message, it is very likely that your maintainer would end up
- hand editing the log message when he applies your patch.
- Things like "Hi, this is my first patch.\n", if you really
- want to put in the patch e-mail, should come after the
- three-dash line that signals the end of the commit message.
-
-
- Pine
- ----
-
- (Johannes Schindelin)
-
- I don't know how many people still use pine, but for those poor
- souls it may be good to mention that the quell-flowed-text is
- needed for recent versions.
-
- ... the "no-strip-whitespace-before-send" option, too. AFAIK it
- was introduced in 4.60.
-
- (Linus Torvalds)
-
- And 4.58 needs at least this.
-
- ---
- diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
- Author: Linus Torvalds <torvalds@g5.osdl.org>
- Date: Mon Aug 15 17:23:51 2005 -0700
-
- Fix pine whitespace-corruption bug
-
- There's no excuse for unconditionally removing whitespace from
- the pico buffers on close.
-
- diff --git a/pico/pico.c b/pico/pico.c
- --- a/pico/pico.c
- +++ b/pico/pico.c
- @@ -219,7 +219,9 @@ PICO *pm;
- switch(pico_all_done){ /* prepare for/handle final events */
- case COMP_EXIT : /* already confirmed */
- packheader();
- +#if 0
- stripwhitespace();
- +#endif
- c |= COMP_EXIT;
- break;
-
-
- (Daniel Barkalow)
-
- > A patch to SubmittingPatches, MUA specific help section for
- > users of Pine 4.63 would be very much appreciated.
-
- Ah, it looks like a recent version changed the default behavior to do the
- right thing, and inverted the sense of the configuration option. (Either
- that or Gentoo did it.) So you need to set the
- "no-strip-whitespace-before-send" option, unless the option you have is
- "strip-whitespace-before-send", in which case you should avoid checking
- it.
-
-
- Thunderbird
- -----------
-
- (A Large Angry SCM)
-
- Here are some hints on how to successfully submit patches inline using
- Thunderbird.
-
- This recipe appears to work with the current [*1*] Thunderbird from Suse.
-
- The following Thunderbird extensions are needed:
- AboutConfig 0.5
- http://aboutconfig.mozdev.org/
- External Editor 0.7.2
- http://globs.org/articles.php?lng=en&pg=8
-
- 1) Prepare the patch as a text file using your method of choice.
-
- 2) Before opening a compose window, use Edit->Account Settings to
- uncheck the "Compose messages in HTML format" setting in the
- "Composition & Addressing" panel of the account to be used to send the
- patch. [*2*]
-
- 3) In the main Thunderbird window, _before_ you open the compose window
- for the patch, use Tools->about:config to set the following to the
- indicated values:
- mailnews.send_plaintext_flowed => false
- mailnews.wraplength => 0
-
- 4) Open a compose window and click the external editor icon.
-
- 5) In the external editor window, read in the patch file and exit the
- editor normally.
-
- 6) Back in the compose window: Add whatever other text you wish to the
- message, complete the addressing and subject fields, and press send.
-
- 7) Optionally, undo the about:config/account settings changes made in
- steps 2 & 3.
-
-
- [Footnotes]
- *1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
- 9.3 professional updates.
-
- *2* It may be possible to do this with about:config and the following
- settings but I haven't tried, yet.
- mail.html_compose => false
- mail.identity.default.compose_html => false
- mail.identity.id?.compose_html => false
-
-
-
- Gnus
- ----
-
- '|' in the *Summary* buffer can be used to pipe the current
- message to an external program, and this is a handy way to drive
- "git am". However, if the message is MIME encoded, what is
- piped into the program is the representation you see in your
- *Article* buffer after unwrapping MIME. This is often not what
- you would want for two reasons. It tends to screw up non ASCII
- characters (most notably in people's names), and also
- whitespaces (fatal in patches). Running 'C-u g' to display the
- message in raw form before using '|' to run the pipe can work
- this problem around.
-
|