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>
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>
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>
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>
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>
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>
Doc update around use of "format-patch --subject-prefix" etc.
* ad/submitting-patches-title-decoration:
doc/SubmittingPatches: correct subject guidance
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>
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>
-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>
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>
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>
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>
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>
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>
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>
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
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>
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>
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>
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>
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>
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>
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>
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?
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>
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>
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>
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>
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
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
Jeff King
Ville Skyttä
Junio C Hamano
Thomas Gummerer
Todd Zullinger
brian m. carlson
Adam Dinwoodie
René Genz
Ævar Arnfjörð Bjarmason
Cornelius Weig
Beat Bolli
Heiko Voigt
Lars Schneider
Eric Sunshine
Stefan Beller
Slavomir Vlcek
René Scharfe
Marc Branchaud
Thomas Ackermann
Adam Spiers
Philip Oakley
Sverre Rabbelier
Jonathan Nieder
Jim Meyering