summaryrefslogtreecommitdiff
path: root/Documentation/SubmittingPatches
AgeCommit message (Collapse)AuthorFilesLines
2021-04-14doc: clarify "do not capitalize the first word" ruleLibravatar Junio C Hamano1-4/+7
The same "do not capitalize the first word" rule is applied to both our patch titles and error messages, but the existing description was fuzzy in two aspects. * For error messages, it was not said that this was only about the first word that begins the sentence. * For both, it was not clear when a capital letter there was not an error. We avoid capitalizing the first word when the only reason you would capitalize it is because it happens to be the first word in the sentence. If a proper noun, which is usually spelled in capital letters, happens to come at the beginning of the sentence, it should be kept in capital letters. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-01-07SubmittingPatches: tighten wording on "sign-off" procedureLibravatar Junio C Hamano1-1/+1
The text says "if you can certify DCO then you add a Signed-off-by trailer". But it does not say anything about people who cannot or do not want to certify. A natural reading may be that if you do not certify, you must not add the trailer, but it shouldn't hurt to be overly explicit. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-11-02Merge branch 'jc/doc-final-resend'Libravatar Junio C Hamano1-3/+5
Update developer doc. * jc/doc-final-resend: SubmittingPatches: clarify the purpose of the final resend
2020-10-26SubmittingPatches: clarify the purpose of the final resendLibravatar Junio C Hamano1-3/+5
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-20Documentation: stylistically normalize references to Signed-off-by:Libravatar Bradley M. Kuhn1-5/+5
Ted reported an old typo in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article. Upon examination, it seems that the documentation (including items in Documentation/, but also option help strings) have been quite inconsistent on usage when referring to `Signed-off-by`. First, very few places used a definite or indefinite article with the phrase "Signed-off-by line", but that was the initial typo that led to this investigation. So, normalize using either an indefinite or definite article consistently. The original phrasing, in Commit 3f971fc425b (Documentation updates, 2005-08-14), is "Add Signed-off-by line". Commit 6f855371a53 (Add --signoff, --check, and long option-names. 2005-12-09) switched to using "Add `Signed-off-by:` line", but didn't normalize the former commit to match. Later commits seem to have cut and pasted from one or the other, which is likely how the usage became so inconsistent. Junio stated on the git mailing list in <xmqqy2k1dfoh.fsf@gitster.c.googlers.com> a preference to leave off the colon. Thus, prefer `Signed-off-by` (with backticks) for the documentation files and Signed-off-by (without backticks) for option help strings. Additionally, Junio argued that "trailer" is now the standard term to refer to `Signed-off-by`, saying that "becomes plenty clear that we are not talking about any random line in the log message". As such, prefer "trailer" over "line" anywhere the former word fits. However, leave alone those few places in documentation that use Signed-off-by to refer to the process (rather than the specific trailer), or in places where mail headers are generally discussed in comparison with Signed-off-by. Reported-by: "Theodore Y. Ts'o" <tytso@mit.edu> Signed-off-by: Bradley M. Kuhn <bkuhn@sfconservancy.org> Acked-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-20SubmittingPatches: clarify DCO is our --signoff ruleLibravatar Junio C Hamano1-11/+14
The description on sign-off and DCO was written back in the days where there was only a choice between "use sign-off and it means the contributor agrees to the Linux-kernel style DCO" and "not using sign-off at all will make your patch unusable". These days, we are trying to clarify that the exact meaning of a sign-off varies project to project. Let's be more explicit when presenting what _our_ rules are. It is of secondary importance that it originally came from the kernel project, so move the description as a historical note at the end, while cautioning that what a sign-off means to us may be different from what it means to other projects contributors may have been used to. Signed-off-by: Junio C Hamano <gitster@pobox.com> Reviewed-by: Taylor Blau <me@ttaylorr.com> Reviewed-by: Bradley M. Kuhn <bkuhn@sfconservancy.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-07-06Merge branch 'js/pu-to-seen'Libravatar Junio C Hamano1-5/+5
The documentation and some tests have been adjusted for the recent renaming of "pu" branch to "seen". * js/pu-to-seen: tests: reference `seen` wherever `pu` was referenced docs: adjust the technical overview for the rename `pu` -> `seen` docs: adjust for the recent rename of `pu` to `seen`
2020-06-25docs: adjust for the recent rename of `pu` to `seen`Libravatar Johannes Schindelin1-5/+5
As of "What's cooking in git.git (Jun 2020, #04; Mon, 22)", there is no longer any `pu` branch, but a `seen` branch. While we technically do not even need to update the manual pages, it makes sense to update them because they clearly talk about branches in git.git. Please note that in two instances, this patch not only updates the branch name, but also the description "(proposed updates)". Where appropriate, quotes have been added for readability. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-06-08docs: mention MyFirstContribution in more placesLibravatar Emily Shaffer1-2/+3
While the MyFirstContribution guide exists and has received some use and positive reviews, it is still not as discoverable as it could be. Add a reference to it from the GitHub pull request template, where many brand-new contributors may look. Also add a reference to it in SubmittingPatches, which is the central source of guidance for patch contribution. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Reviewed-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-10Merge branch 'dl/pretty-reference'Libravatar Junio C Hamano1-5/+11
"git log" family learned "--pretty=reference" that gives the name of a commit in the format that is often used to refer to it in log messages. * dl/pretty-reference: SubmittingPatches: use `--pretty=reference` pretty: implement 'reference' format pretty: add struct cmt_fmt_map::default_date_mode_type pretty: provide short date format t4205: cover `git log --reflog -z` blindspot pretty.c: inline initalize format_context revision: make get_revision_mark() return const pointer completion: complete `tformat:` pretty format SubmittingPatches: remove dq from commit reference pretty-formats.txt: use generic terms for hash SubmittingPatches: use generic terms for hash
2019-11-20SubmittingPatches: use `--pretty=reference`Libravatar Denton Liu1-0/+6
Since Git was taught the `--pretty=reference` option, it is no longer necessary to manually specify the format string to get the commit reference. Teach users to use the new option while keeping the old invocation around in case they have an older version of Git. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-20SubmittingPatches: remove dq from commit referenceLibravatar Denton Liu1-5/+5
Quoting SZEDER Gábor[1], SubmittingPatches is simply wrong: our de-facto standard format for referencing other commits does not enclose the subject in a pair of double-quotes: $ git log v2.24.0 |grep -E '[0-9a-f]{7} \("' |wc -l 785 $ git log v2.24.0 |grep -E '[0-9a-f]{7} \([^"]' |wc -l 2276 Those double-quotes don't add any value to the references, but they result in weird looking references for 1083 of our commits whose subject lines happen to end with double-quotes, e.g.: f23a465132 ("hashmap_get{,_from_hash} return "struct hashmap_entry *"", 2019-10-06) and without those unnecessary pair of double-quotes we would have ~3000 more commits whose summary would fit on a single line. Remove references to the enclosing double-quotes from SubmittingPatches since our de-facto standard for referencing commits does not actually use them. [1]: cf. <20191114011048.GS4348@szeder.dev> Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-20SubmittingPatches: use generic terms for hashLibravatar Denton Liu1-1/+1
Since Git is planning on upgrading from SHA-1 to be more hash-agnostic, replace specific references to SHA-1 with more generic terminology. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-18SubmittingPatches: git-gui has a new maintainerLibravatar Junio C Hamano1-2/+2
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-13doc: format pathnames and URLs as monospace.Libravatar Corentin BOMPARD1-3/+3
Applying CodingGuidelines about monospace on pathnames and URLs. See Documentation/CodingGuidelines.txt for more information. Signed-off-by: Corentin BOMPARD <corentin.bompard@etu.univ-lyon1.fr> Signed-off-by: Nathan BERBEZIER <nathan.berbezier@etu.univ-lyon1.fr> Signed-off-by: Pablo CHABANNE <pablo.chabanne@etu.univ-lyon1.fr> Signed-off-by: Matthieu MOY <matthieu.moy@univ-lyon1.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-08-21SubmittingPatches: mention doc-diffLibravatar Jeff King1-1/+3
We already advise people to make sure their documentation formats correctly. Let's point them at the doc-diff script, which can help with that. Let's also put a brief note in the script about its purpose, since that otherwise can only be found in the original commit message. Along with the existing -h/usage text, that's hopefully enough for developers to make use of it. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-22Documentation: spelling and grammar fixesLibravatar Ville Skyttä1-2/+2
Signed-off-by: Ville Skyttä <ville.skytta@iki.fi> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-04Merge branch 'tg/doc-sec-list'Libravatar Junio C Hamano1-4/+17
Doc update. * tg/doc-sec-list: note git-security@googlegroups.com in more places SubmittingPatches: replace numbered attributes with names
2018-06-01note git-security@googlegroups.com in more placesLibravatar Thomas Gummerer1-0/+13
Add a mention of the security mailing list to the README, and to Documentation/SubmittingPatches.. 2caa7b8d27 ("git manpage: note git-security@googlegroups.com", 2018-03-08) already added it to the man page, but for developers either the README, or the documentation on how to contribute (SubmittingPatches) may be the first place to look. Use the same wording as we already have on the git-scm.com website and in the man page for the README, while the wording is adjusted in SubmittingPatches to match the surrounding document better. Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-01SubmittingPatches: replace numbered attributes with namesLibravatar Thomas Gummerer1-4/+4
Use names instead of numbers for the AsciiDoc attributes that are used for the footnotes. We will add more footnotes in subsequent commits, and attributes should ideally all be unique. Having named attributes will help ensure uniqueness, and we won't have to re-number the attributes if we add a footnote earlier in the document. In addition it also clarifies that the attribute name/number is not related to the number the footnote will get in the output. Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-12SubmittingPatches: mention the git contacts commandLibravatar Thomas Gummerer1-2/+2
Instead of just mentioning 'git blame' and 'git shortlog', which make it quite hard for new contributors to pick out the appropriate list of people to cc on their patch series, mention the 'git contacts' utility, which makes it much easier to get a reasonable list of contacts for a change. This should help new contributors pick out a reasonable cc list by simply using a single command. Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-01-09Merge branch 'bc/submitting-patches-in-asciidoc'Libravatar Junio C Hamano1-1/+1
Doc readability update. * bc/submitting-patches-in-asciidoc: doc/SubmittingPatches: improve text formatting
2018-01-03doc/SubmittingPatches: improve text formattingLibravatar Todd Zullinger1-1/+1
049e64aa50 ("Documentation: convert SubmittingPatches to AsciiDoc", 2017-11-12) changed the `git blame` and `git shortlog` examples given in the section on sending your patches. In order to italicize the `$path` argument the commands are enclosed in plus characters as opposed to backticks. The difference between the quoting methods is that backtick enclosed text is not subject to further expansion. This formatting makes reading SubmittingPatches in a git clone a little more difficult. In addition to the underscores around `$path` the `--` chars in `git shortlog --no-merges` must be replaced with `{litdd}`. Use backticks to quote these commands. The italicized `$path` is lost from the html version but the commands can be read (and copied) more easily by users reading the text version. These readers are more likely to use the commands while submitting patches. Make it easier for them. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
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?