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>
-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>
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>
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>
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>
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>
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>
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>
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>
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>
Add a section 0 explaining which commit to base patches on.
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even if you use imap-send to throw your drafts in the outbox, using their
web interface will mangle your patches. Clarify that the imap-send is
meant to be used together with a real MUA that can use IMAP drafts, and
remove instructions related to the web interface, which is irrelevant.
Add description of send-email as an alternative.
Use --cover-letter, and do not use -C nor --no-color, on the example
command line for format-patch.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"What happened to my patch" is pretty much a FAQ on the Git mailing list,
it deserves a few paragraphs in SubmittingPatches...
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The SubmittingPatches file was trimmed down from a somewhat
overwhelming set of requirements from the Linux Kernel equivalent;
however perhaps a little of it can be returned without making the
text too long.
Signed-off-by: Sam Vilain <sam@vilain.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Also add a comment that the web interface wraps the lines
Signed-off-by: John Tapsell <johnflux@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Especially with something that is supposed to hopefully have some legal
value down the line if somebody starts making noises, it really would be
nice to have a real person to associate things with. Suggest this in the
SubmittingPatches document.
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Gmail is one of the most popular email providers in the world. Now that Gmail
supports IMAP, sending properly formatted patches via `git imap-send` is
trivial. This section in SubmittingPatches explains how to do so.
Signed-off-by: Tom Preston-Werner <tom@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
With git-am, it sounds awkward to have the patches in ".git/rebase/",
but for technical reasons, we have to keep the same directory name
for git-am and git-rebase. ".git/rebase-apply" seems to be a good
compromise.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since the files generated and used during a rebase are never to be
tracked, they should live in $GIT_DIR. While at it, avoid the rather
meaningless term "dotest" to "rebase", and unhide ".dotest-merge".
This was wished for on the mailing list, but so far unimplemented.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The script appp.sh can be used with the External Editor extension for
Mozilla Thunderbird in order to be able to send inline patches in an
easy way.
Signed-off-by: Lukas Sandström <lukass@etek.chalmers.se>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We used to talk about "internal company procedures", but this
document is about submitting patches to the git mailing list.
More useful information is when to say Acked-by: and Tested-by:.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
brian m. carlson