summaryrefslogtreecommitdiff
path: root/Documentation/SubmittingPatches
AgeCommit message (Collapse)AuthorFilesLines
2017-11-21Merge branch 'ad/submitting-patches-title-decoration'Libravatar Junio C Hamano1-8/+13
Doc update around use of "format-patch --subject-prefix" etc. * ad/submitting-patches-title-decoration: doc/SubmittingPatches: correct subject guidance
2017-11-13Documentation: convert SubmittingPatches to AsciiDocLibravatar brian m. carlson1-161/+185
The SubmittingPatches document is often cited by outside parties as an example of good practices to follow, including logical, independent commits; patch sign-offs; and sending patches to a mailing list. Currently, people who want to cite a particular section tend to either refer to it by name and let the interested party search through the document to find it, or link to a given line number on GitHub and hope the file doesn't change. Instead, convert the document to AsciiDoc. Build it as part of the technical documentation, since it is likely of interest to the same group of people. Provide stable links to the sections which outside parties are likely to want to link to. Make some minor structural changes to organize it so that it can be formatted sanely. Since the makefile needs a .txt extension in order to build with the rest of the documentation, simply copy the file. Ignore the temporary file so it doesn't get checked in accidentally, and remove it as part of the clean process. Do this instead of renaming the file so that people who have already linked to the documentation (who we're trying to help) don't find their links broken. Avoid symlinking since Windows will not like that. This allows us to render the document as part of the website for the benefit of others who wish to link to it as well as providing a more nicely formatted display for our community and potential contributors. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-11-11doc/SubmittingPatches: correct subject guidanceLibravatar Adam Dinwoodie1-8/+13
The examples and common practice for adding markers such as "RFC" or "v2" to the subject of patch emails is to have them within the same brackets as the "PATCH" text, not after the closing bracket. Further, the practice of `git format-patch` and the like, as well as what appears to be the more common pratice on the mailing list, is to use "[RFC PATCH]", not "[PATCH/RFC]". Update the SubmittingPatches article to match and to reference the `format-patch` helper arguments, and also make some minor text clarifications in the area. Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-05-04Merge branch 'rg/doc-submittingpatches-wordfix'Libravatar Junio C Hamano1-6/+6
* rg/doc-submittingpatches-wordfix: doc: update SubmittingPatches
2017-05-01doc: update SubmittingPatchesLibravatar René Genz1-6/+6
-use US English spelling -minor wording change for better readability Helped-by: Stefan Beller <sbeller@google.com> Signed-off-by: René Genz <liebundartig@freenet.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-26doc/SubmittingPatches: show how to get a CLI commit summaryLibravatar Ævar Arnfjörð Bjarmason1-1/+2
Amend the section which describes how to get a commit summary to show how do to that with "git show", currently the documentation only shows how to do that with gitk. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-21doc/SubmittingPatches: clarify the casing convention for "area: change..."Libravatar Ævar Arnfjörð Bjarmason1-2/+7
Amend the section which describes how the first line of the subject should look like to say that the ":" in "area: " shouldn't be treated like a full stop for the purposes of letter casing. Change the two subject examples to make this new paragraph clearer, i.e. "unstar" is not a common word, and "git-cherry-pick.txt" is a much longer string than "githooks.txt". Pick two recent commits from git.git that fit better for the description. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-27doc: clarify distinction between sign-off and pgp-signingLibravatar Cornelius Weig1-7/+6
The documentation for submission discourages pgp-signing, but demands a proper sign-off by contributors. However, when skimming the headings, the wording of the section for sign-off could mistakenly be understood as concerning pgp-signing. Thus, new contributors could oversee the necessary sign-off. This commit improves the wording such that the section about sign-off cannot be misunderstood as pgp-signing. In addition, the paragraph about pgp-signing is changed such that it avoids the impression that pgp-signing could be relevant at later stages of the submission. Signed-off-by: Cornelius Weig <cornelius.weig@tngtech.com> Helped-by: Philip Oakley <philipoakley@iee.org> Helped-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-08-26SubmittingPatches: use gitk's "Copy commit summary" formatLibravatar Beat Bolli1-3/+8
Update the suggestion in 175d38ca ("SubmittingPatches: document how to reference previous commits", 2016-07-28) on the format to refer to a commit to match what gitk has been giving since last year with its "Copy commit summary" command; also mention this as one of the ways to obtain a commit reference in this format. Signed-off-by: Beat Bolli <dev+git@drbeat.li> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-08-17SubmittingPatches: document how to reference previous commitsLibravatar Heiko Voigt1-0/+5
To reference previous commits people used to put just the abbreviated SHA-1 into commit messages. This is what has evolved as a more stable format for referencing commits. So lets document it for everyone to look-up when needed. Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-05-02Documentation: add setup instructions for Travis CILibravatar Lars Schneider1-17/+63
Also change UK english "behaviour" to US english "behavior". Signed-off-by: Lars Schneider <larsxschneider@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-25Merge branch 'jc/submitting-patches-mention-send-email'Libravatar Junio C Hamano1-0/+5
Recommend format-patch and send-email for those who want to submit patches to this project. * jc/submitting-patches-mention-send-email: SubmittingPatches: encourage users to use format-patch and send-email
2015-03-15SubmittingPatches: encourage users to use format-patch and send-emailLibravatar Junio C Hamano1-0/+5
In step "(4) Sending your patches", we instruct users to do an inline patch, avoid breaking whitespaces, avoid attachments, use [PATCH v2] for second round, etc., all of which format-patch and send-email combo know how to do well. The need was identified by, and the text is based on the work by Cody Taylor. Suggested-by: Cody Taylor <cody.taylor@maternityneighborhood.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-01-12Merge branch 'sb/doc-submitting-patches-keep-notes'Libravatar Junio C Hamano1-2/+5
* sb/doc-submitting-patches-keep-notes: SubmittingPatches: explain rationale for using --notes with format-patch
2015-01-07Merge branch 'sb/dco-indentation-fix'Libravatar Junio C Hamano1-6/+6
* sb/dco-indentation-fix: Documentation/SubmittingPatches: unify whitespace/tabs for the DCO
2015-01-07SubmittingPatches: explain rationale for using --notes with format-patchLibravatar Eric Sunshine1-2/+5
While here, also change grammatically poor "three dash lines" to "three-dash line". Suggested-by: Stefan Beller <sbeller@google.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-12-22Merge branch 'jc/refer-to-t-readme-from-submitting-patches'Libravatar Junio C Hamano1-1/+2
* jc/refer-to-t-readme-from-submitting-patches: t/README: justify why "! grep foo" is sufficient SubmittingPatches: refer to t/README for tests
2014-12-22Documentation/SubmittingPatches: unify whitespace/tabs for the DCOLibravatar Stefan Beller1-6/+6
The Developers Certificate of Origin has a mixture of tabs and white spaces which is annoying to view if your editor explicitly views white space characters. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-11-24SubmittingPatches: refer to t/README for testsLibravatar Junio C Hamano1-1/+2
There are general guidelines for writing good tests in t/README but neither SubmittingPatches nor CodingGuidelines refers to it, which makes the document easy to be missed. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-11-13SubmittingPatches: final submission is To: maintainer and CC: listLibravatar Slavomir Vlcek1-1/+1
In an earlier part there is: "re-send it with "To:" set to the maintainer [*1*] and "cc:" the list [*2*]" for the final submission, but later we see "Send it to the list and cc the maintainer." Fix the later one to match the previous. Signed-off-by: Slavomir Vlcek <svlc@inventati.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-12-17Merge branch 'rs/doc-submitting-patches' into maintLibravatar Junio C Hamano1-2/+9
* rs/doc-submitting-patches: SubmittingPatches: document how to handle multiple patches
2013-12-12Merge branch 'rs/doc-submitting-patches'Libravatar Junio C Hamano1-2/+9
* rs/doc-submitting-patches: SubmittingPatches: document how to handle multiple patches
2013-11-27SubmittingPatches: document how to handle multiple patchesLibravatar René Scharfe1-2/+9
Signed-off-by: Rene Scharfe <l.s.r@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-01Provide some linguistic guidance for the documentation.Libravatar Marc Branchaud1-1/+14
This will hopefully avoid questions over which spelling and grammar should be used. Translators are of course free to create localizations for specific English dialects. Signed-off-by: Marc Branchaud <marcnarc@xiplink.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-5/+5
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: avoid poor-man's small caps GITLibravatar Thomas Ackermann1-1/+1
In the earlier days, we used to spell the name of the system as GIT, to simulate as if it were typeset with capital G and IT in small caps. Later we stopped doing so at around 1.6.5 days. Let's stop doing so throughout the documentation. The name to refer to the whole system (and the concept it embodies) is "Git"; the command end-users type is "git". And document this in the coding guideline. Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-09Merge branch 'jc/submittingpatches'Libravatar Junio C Hamano1-84/+91
Streamline the document and update with a few e-mail addresses the patches should be sent to. * jc/submittingpatches: SubmittingPatches: give list and maintainer addresses SubmittingPatches: remove overlong checklist SubmittingPatches: mention subsystems with dedicated repositories SubmittingPatches: who am I and who cares?
2013-01-02SubmittingPatches: give list and maintainer addressesLibravatar Junio C Hamano1-2/+6
We told readers to "send it to the list" (or the maintainer) without telling what addresses are to be used. Correct this. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-02SubmittingPatches: remove overlong checklistLibravatar Junio C Hamano1-76/+61
The section is no longer a concise checklist. It also talks about things that are not covered in the "Long version" text, which means people need to read both, covering more or less the same thing in different phrasing. Fold the details into the main text and remove the section. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-01SubmittingPatches: mention subsystems with dedicated repositoriesLibravatar Junio C Hamano1-0/+24
These were only mentioned in periodical "A note from the maintainer" posting and not in the documentation suite. SubmittingPatches has a section to help contributors decide on what commit to base their changes, which is the most suitable place for this information. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-01SubmittingPatches: who am I and who cares?Libravatar Junio C Hamano1-8/+2
The introductory text in the "long version" talks about the origin of this document with "I started ...", but it is unclear who that I is, and more importantly, it is not interesting how it was started. Just state the purpose of the document to help readers decide if it is releavant to them. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-21Merge branch 'as/doc-for-devs'Libravatar Junio C Hamano1-13/+8
It might be a better idea to move the text the bottom one adds to the extended description from the quick checklist part. * as/doc-for-devs: Documentation: move support for old compilers to CodingGuidelines SubmittingPatches: add convention of prefixing commit messages
2012-12-16Documentation: move support for old compilers to CodingGuidelinesLibravatar Adam Spiers1-13/+0
The "Try to be nice to older C compilers" text is clearly a guideline to be borne in mind whilst coding rather than when submitting patches. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-12-16SubmittingPatches: add convention of prefixing commit messagesLibravatar Adam Spiers1-0/+8
Conscientious newcomers to git development will read SubmittingPatches and CodingGuidelines, but could easily miss the convention of prefixing commit messages with a single word identifying the file or area the commit touches. Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-10-25Doc SubmittingPatches: Mention --notes option after "cover letter"Libravatar Philip Oakley1-1/+2
The git format-patch --notes option can now insert the commit notes after the three dashes. Mention this after the regular cover letter guidance for submitting patches. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Jeff King <peff@peff.net>
2011-09-11SubmittingPathces: remove Cogito referenceLibravatar Sverre Rabbelier1-2/+1
Removing Cogito leaves just git and StGit, which is a rather incomplete list of git diff tools available. Sidestep the problem of deciding what tools to mention by not mentioning any. Signed-off-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-15Documentation: publicize hints for sending patches with GMailLibravatar Jonathan Nieder1-52/+2
The hints in SubmittingPatches about stopping GMail from clobbering patches are widely useful both as examples of "git send-email" and "git imap-send" usage. Move the documentation to the appropriate places. While at it, don't encourage storing passwords in config files. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-15Documentation: publicize KMail hints for sending patches inlineLibravatar Jonathan Nieder1-20/+2
These hints are in git's private SubmittingPatches document but a wider audience might be interested. Move them to the "git format-patch" manpage. I'm not sure what gotchas these hints are meant to work around. They might be completely false. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-15Documentation: hints for sending patches inline with ThunderbirdLibravatar Jonathan Nieder1-80/+1
The standard reference for this information is the article "Plain text e-mail - Thunderbird#Completely_plain_email" at kb.mozillazine.org, but the hints hidden away in git's SubmittingPatches file are more complete. Move them to the "git format-patch" manual so they can be installed with git and read by a wide audience. While at it, make some tweaks: - update "Approach #1" so it might work with Thunderbird 3; - remove ancient version numbers from the descriptions of both approaches so current readers might have more reason to complain if they don't work. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-15Documentation: explain how to check for patch corruptionLibravatar Jonathan Nieder1-44/+14
SubmittingPatches has some excellent advice about how to check a patch for corruption before sending it off. Move it to the format-patch manual so it can be installed with git's documentation for use by people not necessarily interested in the git project's practices. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-13remove doubled words, e.g., s/to to/to/, and fix related typosLibravatar Jim Meyering1-2/+1
I found that some doubled words had snuck back into projects from which I'd already removed them, so now there's a "syntax-check" makefile rule in gnulib to help prevent recurrence. Running the command below spotted a few in git, too: git ls-files | xargs perl -0777 -n \ -e 'while (/\b(then?|[iao]n|i[fst]|but|f?or|at|and|[dt])\s+\1\b/gims)' \ -e '{$n=($` =~ tr/\n/\n/ + 1); ($v=$&)=~s/\n/\\n/g;' \ -e 'print "$ARGV:$n:$v\n"}' Signed-off-by: Jim Meyering <meyering@redhat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-08SubmittingPatches: clarify the expected commit log descriptionLibravatar Junio C Hamano1-8/+18
Earlier, 47afed5 (SubmittingPatches: itemize and reflect upon well written changes, 2009-04-28) added a discussion on the contents of the commit log message, but the last part of the new paragraph didn't make much sense. Reword it slightly to make it more readable. Update the "quicklist" to clarify what we mean by "motivation" and "contrast". Also mildly discourage external references. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-06SubmittingPatches: Document some extra tags used in commit messagesLibravatar Ramkumar Ramachandra1-6/+15
Document the meanings of the tags "Reported-by:", "Acked-by:", "Reviewed-by:" and "Tested-by:" clearly. Also mention that the user is free to use any custom tags. Helped-by: Jonathan Nieder <jrnieder@gmail.com> Liked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-28SubmittingPatches: Cite the 50 char subject limitLibravatar Ævar Arnfjörð Bjarmason1-1/+2
Change the SubmittingPatches recommendations to mention the 50 character soft limit on patch subject lines. 50 characters is the soft limit mentioned in git-commit(1) and gittutorial(7), it's also the point at which Gitweb, GitHub and various other Git front ends start abbreviating the commit message. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-28SubmittingPatches: Clarify the Signed-off-by rulesLibravatar Ævar Arnfjörð Bjarmason1-5/+3
The wording of the Signed-off-by rules could be read as stating that S-O-B should only be added when the submitter considered the patch ready for inclusion in git.git. We also want Signed-off-by to be used for e.g. RFC patches, in case someone wants to dig an old patch out of the archive and improve it. Change the wording to recommend a Signed-off-by for all submitted patches. The problem with the wording came up in the "[PATCH/RFC] Hacky version of a glob() driven config include" thread[1]. Bert Wesarg suggested[2] that it be removed to avoid confusion, which this change implements. 1. <1273180440-8641-1-git-send-email-avarab@gmail.com> 2. <AANLkTimziTKL13VKIOcaS1TX1F_xvTVjH8Q398Yx36Us@mail.gmail.com> Suggested-by: Bert Wesarg <bert.wesarg@googlemail.com> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-05-31Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
* maint: Documentation/SubmittingPatches: Fix typo in GMail section Documentation/config: describe status.submodulesummary
2010-05-31Documentation/SubmittingPatches: Fix typo in GMail sectionLibravatar Tim Henigan1-1/+1
Commit e498257d introduced a typo while improving the GMail section of SubmittingPatches. Signed-off-by: Tim Henigan <tim.henigan@gmail.com> Acked-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-05-25Merge branch 'maint'Libravatar Junio C Hamano1-19/+21
* maint: Documentation/SubmittingPatches: clarify GMail section and SMTP show-branch: use DEFAULT_ABBREV instead of 7 t7502-commit: fix spelling test get_git_work_tree() return value for NULL
2010-05-25Documentation/SubmittingPatches: clarify GMail section and SMTPLibravatar Michael J Gruber1-19/+21
We keep getting mangled submissions from GMail's web interface. Try to be more proactive in SubmittingPatches by - pointing to MUA specific instructions early on, - structuring the GMail section more clearly, - putting send-email/SMTP before imap-send/IMAP. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-05-21Merge branch 'rr/doc-submitting'Libravatar Junio C Hamano1-11/+38
* rr/doc-submitting: SubmittingPatches: Add new section about what to base work on