Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
On Tue, Oct 31, 2017 at 6:21 PM, Johannes Schindelin wrote: > Hi Paolo, > > On Mon, 30 Oct 2017, Paolo Ciarrocchi wrote: > >> On Mon, Oct 30, 2017 at 1:35 PM, Johannes Schindelin >> wrote: >> > >> > On Mon, 30 Oct 2017, Junio C Hamano wrote: >> > >> >> "brian m. carlson" writes: >> >> >> >> Thanks. I personally prefer the plain-text original, but I do >> >> understand the need to have a version with ids that you can tell >> >> others to visit in their browsers. Assuming that this goes in the >> >> right direction, here are a few comments. >> > >> > If you want to go into the direction of the web, AsciiDoc is actually the >> > wrong choice IMO, and Markdown would be the right choice. Basically >> > everybody on the web is either supporting Markdown or being asked by users >> > to do so. >> > >> > Assuming that *that* is something we want to pursue, I would also suggest >> > to move the man pages away from AsciiDoc to Markdown (using e.g. >> > [ronn](https://rtomayko.github.io/ronn/ronn.1.html)). >> >> Nitpick, the right URL is: https://rtomayko.github.io/ronn/ronn.1.html >> You put an extra ')' at the end and therefore I've got a scaring 404 error >> :-) > > The first closing parenthesis closes the link associated with the label > `ronn`, the second closing parenthesis closes the remark I started in the > previous line (beginning with the word "using"). You are right. I've got confused by the fact that gmail fails to properly handle that link. Sorry for the noise. Regards, -- Paolo
Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
Hi Paolo, On Mon, 30 Oct 2017, Paolo Ciarrocchi wrote: > On Mon, Oct 30, 2017 at 1:35 PM, Johannes Schindelin > wrote: > > > > On Mon, 30 Oct 2017, Junio C Hamano wrote: > > > >> "brian m. carlson" writes: > >> > >> Thanks. I personally prefer the plain-text original, but I do > >> understand the need to have a version with ids that you can tell > >> others to visit in their browsers. Assuming that this goes in the > >> right direction, here are a few comments. > > > > If you want to go into the direction of the web, AsciiDoc is actually the > > wrong choice IMO, and Markdown would be the right choice. Basically > > everybody on the web is either supporting Markdown or being asked by users > > to do so. > > > > Assuming that *that* is something we want to pursue, I would also suggest > > to move the man pages away from AsciiDoc to Markdown (using e.g. > > [ronn](https://rtomayko.github.io/ronn/ronn.1.html)). > > Nitpick, the right URL is: https://rtomayko.github.io/ronn/ronn.1.html > You put an extra ')' at the end and therefore I've got a scaring 404 error :-) The first closing parenthesis closes the link associated with the label `ronn`, the second closing parenthesis closes the remark I started in the previous line (beginning with the word "using"). Ciao, Johannes
Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
On Mon, Oct 30, 2017 at 01:28:05PM +0900, Junio C Hamano wrote:
> "brian m. carlson" writes:
>
> Thanks. I personally prefer the plain-text original, but I do
> understand the need to have a version with ids that you can tell
> others to visit in their browsers. Assuming that this goes in the
> right direction, here are a few comments.
>
> > @@ -58,8 +65,9 @@ differs substantially from the prior version, are all
> > good things
> > to have.
> >
> > Make sure that you have tests for the bug you are fixing. See
> > -t/README for guidance.
> > +'t/README' for guidance.
>
> I am guessing that, from the way you updated 'next' to `next'
> etc. in the previous hunk, you are typesetting in anything a
> reader may type literally without substitution.
>
> Should this be `t/README`, as it is a part of something a reader may
> type literally (as in "less t/README")?
So this syntax provides italicized paths, but I agree that the is
better here. I'll make those changes throughout, and fix up the
instances of that you mentioned.
> > -(4) Sending your patches.
> > +[[send-patches]]
> > +=== Sending your patches.
> > +:1: footnote:[The current maintainer: gits...@pobox.com]
> > +:2: footnote:[The mailing list: git@vger.kernel.org]
>
> Having to see these footnotes upfront is somewhat distracting for
> those of us who prefer to use this file as a text document. I see
> these become part of the footnotes section at the very end of the
> document (as opposed to the end of this section), so even with the
> rendered output it does not look ideal.
>
> I am not sure how much these two points matter, though.
AsciiDoc requires that the attributes appear before their references. I
can move the attributes just before the paragraph they refer to, or I
can inline the footnotes. I could also just turn them into links if
that works better.
This is actually one thing that I think Markdown does better.
> > @@ -191,7 +212,7 @@ not ready to be applied but it is for discussion,
> > [PATCH v2],
> > ..
> > Send your patch with "To:" set to the mailing list, with "cc:" listing
> > people who are involved in the area you are touching (the output from
> > -"git blame $path" and "git shortlog --no-merges $path" would help to
> > ++git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help
> > to
> > identify them), to solicit comments and reviews.
>
> The +fixed width with _italics_ mixed in+ mark-up is something not
> exactly new, but it is rarely used in our documentation set, so I
> had to double check by actually seeing how it got rendered, and it
> looked alright.
I thought it provided some hint to the reader that this wasn't meant to
be typed literally. It's a preference of mine and I think it aids in
readability, but it can be changed if we want.
> > After the list reached a consensus that it is a good idea to apply the
> > -patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
> > -list [*2*] for inclusion.
> > +patch, re-send it with "To:" set to the maintainer{1} and "cc:" the
> > +list{2} for inclusion.
> >
> > Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
> > "Tested-by:" lines as necessary to credit people who helped your
> > patch.
>
> Should these "Foo-by:" all be `Foo-by:`?
I'll make these changes as well.
> > -An ideal patch flow
> > +[[patch-flow]]
> > +== An ideal patch flow
> >
> > Here is an ideal patch flow for this project the current maintainer
> > suggests to the contributors:
> >
> > - (0) You come up with an itch. You code it up.
> > +. You come up with an itch. You code it up.
> >
> > - (1) Send it to the list and cc people who may need to know about
> > - the change.
> > +. Send it to the list and cc people who may need to know about
> > + the change.
> > ++
> > +The people who may need to know are the ones whose code you
> > +are butchering. These people happen to be the ones who are
> > +most likely to be knowledgeable enough to help you, but
> > +they have no obligation to help you (i.e. you ask for help,
> > +don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
> > +help you find out who they are.
> >
> > - The people who may need to know are the ones whose code you
> > - are butchering. These people happen to be the ones who are
> > - most likely to be knowledgeable enough to help you, but
> > - they have no obligation to help you (i.e. you ask for help,
> > - don't demand). "git log -p -- $area_you_are_modifying" would
> > - help you find out who they are.
> > +. You get comments and suggestions for improvements. You may
> > + even get them in a "on top of your change" patch form.
> >
> > - (2) You get comments and suggestions for improvements. You may
> > - even get them in a "on top of your change" patch form.
> > +. Polish, refine, and re-send to the list and the people who
> > + spend their time to improve your patch. Go back to step (2).
>
Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
On Mon, Oct 30, 2017 at 01:35:19PM +0100, Johannes Schindelin wrote: > If you want to go into the direction of the web, AsciiDoc is actually the > wrong choice IMO, and Markdown would be the right choice. Basically > everybody on the web is either supporting Markdown or being asked by users > to do so. > > Assuming that *that* is something we want to pursue, I would also suggest > to move the man pages away from AsciiDoc to Markdown (using e.g. > [ronn](https://rtomayko.github.io/ronn/ronn.1.html)). The thing I really like about AsciiDoc is that it works well for a variety of output formats. Markdown is designed for HTML, and only HTML. It may have converters to other formats, but then you can't use any extension mechanisms in HTML. Markdown also lacks features that AsciiDoc has, like cross-references, named anchors, and the ability to write the linkgit syntax. AsciiDoc, via DocBook and the XSLT stylesheets, supports conversion to PDF, DVI, PS, and ePub, among others. The things I'm seeing for Markdown to PDF involve either Pandoc or a browser engine such as phantomjs. Also, AsciiDoc has the benefit that it has only two implementations. Markdown has so many variants that it's hard to write things like tables in a portable way, so we're going to have at least as many problems (between the website and the codebase) as we do now. -- brian m. carlson / brian with sandals: Houston, Texas, US https://www.crustytoothpaste.net/~bmc | My opinion only OpenPGP: https://keybase.io/bk2204 signature.asc Description: PGP signature
Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
On Mon, Oct 30, 2017 at 1:35 PM, Johannes Schindelin wrote: > Hi, > > On Mon, 30 Oct 2017, Junio C Hamano wrote: > >> "brian m. carlson" writes: >> >> Thanks. I personally prefer the plain-text original, but I do >> understand the need to have a version with ids that you can tell >> others to visit in their browsers. Assuming that this goes in the >> right direction, here are a few comments. > > If you want to go into the direction of the web, AsciiDoc is actually the > wrong choice IMO, and Markdown would be the right choice. Basically > everybody on the web is either supporting Markdown or being asked by users > to do so. > > Assuming that *that* is something we want to pursue, I would also suggest > to move the man pages away from AsciiDoc to Markdown (using e.g. > [ronn](https://rtomayko.github.io/ronn/ronn.1.html)). Nitpick, the right URL is: https://rtomayko.github.io/ronn/ronn.1.html You put an extra ')' at the end and therefore I've got a scaring 404 error :-) Ciao, -- Paolo
Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
Hi, On Mon, 30 Oct 2017, Junio C Hamano wrote: > "brian m. carlson" writes: > > Thanks. I personally prefer the plain-text original, but I do > understand the need to have a version with ids that you can tell > others to visit in their browsers. Assuming that this goes in the > right direction, here are a few comments. If you want to go into the direction of the web, AsciiDoc is actually the wrong choice IMO, and Markdown would be the right choice. Basically everybody on the web is either supporting Markdown or being asked by users to do so. Assuming that *that* is something we want to pursue, I would also suggest to move the man pages away from AsciiDoc to Markdown (using e.g. [ronn](https://rtomayko.github.io/ronn/ronn.1.html)). Ciao, Dscho
Re: [PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
"brian m. carlson" writes:
Thanks. I personally prefer the plain-text original, but I do
understand the need to have a version with ids that you can tell
others to visit in their browsers. Assuming that this goes in the
right direction, here are a few comments.
> @@ -58,8 +65,9 @@ differs substantially from the prior version, are all good
> things
> to have.
>
> Make sure that you have tests for the bug you are fixing. See
> -t/README for guidance.
> +'t/README' for guidance.
I am guessing that, from the way you updated 'next' to `next'
etc. in the previous hunk, you are typesetting in anything a
reader may type literally without substitution.
Should this be `t/README`, as it is a part of something a reader may
type literally (as in "less t/README")?
> @@ -84,41 +92,45 @@ turning en_UK spelling to en_US). Obvious typographical
> fixes are much
> ...
> changes do not trigger errors with the sample pre-commit hook shipped
> -in templates/hooks--pre-commit. To help ensure this does not happen,
> -run "git diff --check" on your changes before you commit.
> +in templates/hooks{litdd}pre-commit. To help ensure this does not happen,
> +run `git diff --check` on your changes before you commit.
The pathname templates/hooks--pre-commit is typeset just like any
body text?
> @@ -154,8 +173,10 @@ sending out, please make sure it cleanly applies to the
> "master"
Out of context, but "master" we see above should probably be
`master` here, to be in line with what you did in an earlier hunk.
So should "next" we see below in the pre-context of this hunk.
> -(4) Sending your patches.
> +[[send-patches]]
> +=== Sending your patches.
> +:1: footnote:[The current maintainer: gits...@pobox.com]
> +:2: footnote:[The mailing list: git@vger.kernel.org]
Having to see these footnotes upfront is somewhat distracting for
those of us who prefer to use this file as a text document. I see
these become part of the footnotes section at the very end of the
document (as opposed to the end of this section), so even with the
rendered output it does not look ideal.
I am not sure how much these two points matter, though.
> @@ -191,7 +212,7 @@ not ready to be applied but it is for discussion, [PATCH
> v2],
> ..
> Send your patch with "To:" set to the mailing list, with "cc:" listing
> people who are involved in the area you are touching (the output from
> -"git blame $path" and "git shortlog --no-merges $path" would help to
> ++git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to
> identify them), to solicit comments and reviews.
The +fixed width with _italics_ mixed in+ mark-up is something not
exactly new, but it is rarely used in our documentation set, so I
had to double check by actually seeing how it got rendered, and it
looked alright.
> After the list reached a consensus that it is a good idea to apply the
> -patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
> -list [*2*] for inclusion.
> +patch, re-send it with "To:" set to the maintainer{1} and "cc:" the
> +list{2} for inclusion.
>
> Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
> "Tested-by:" lines as necessary to credit people who helped your
> patch.
Should these "Foo-by:" all be `Foo-by:`?
> @@ -302,85 +325,86 @@ D-C-O. Indeed you are encouraged to do so. Do not
> forget to
> ...
> +. "Reported-by:" is used to credit someone who found the bug that
> + the patch attempts to fix.
> +. "Acked-by:" says that the person who is more familiar with the area
> + the patch attempts to modify liked the patch.
> +. "Reviewed-by:", unlike the other tags, can only be offered by the
> + reviewer and means that she is completely satisfied that the patch
> + is ready for application. It is usually offered only after a
> + detailed review.
> +. "Tested-by:" is used to indicate that the person applied the patch
> + and found it to have the desired effect.
Ditto.
> -An ideal patch flow
> +[[patch-flow]]
> +== An ideal patch flow
>
> Here is an ideal patch flow for this project the current maintainer
> suggests to the contributors:
>
> - (0) You come up with an itch. You code it up.
> +. You come up with an itch. You code it up.
>
> - (1) Send it to the list and cc people who may need to know about
> - the change.
> +. Send it to the list and cc people who may need to know about
> + the change.
> ++
> +The people who may need to know are the ones whose code you
> +are butchering. These people happen to be the ones who are
> +most likely to be knowledgeable enough to help you, but
> +they have no obligation to help you (i.e. you ask for help,
> +don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
> +help you find out who they are.
>
> - The people who may need to know are the ones whose code you
> - are butchering. These people happen to be the ones who are
> - most likely to be knowledgeable enough to help you, but
> - they have no
[PATCH 2/2] Documentation: convert SubmittingPatches to AsciiDoc
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 --- Documentation/.gitignore| 1 + Documentation/Makefile | 5 + Documentation/SubmittingPatches | 331 +--- 3 files changed, 183 insertions(+), 154 deletions(-) diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 2c8b2d612e..c7096f11f1 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -11,3 +11,4 @@ doc.dep cmds-*.txt mergetools-*.txt manpage-base-url.xsl +SubmittingPatches.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index d5ad85459e..2ab65561af 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -67,6 +67,7 @@ SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += SubmittingPatches TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/index-format @@ -324,6 +325,7 @@ clean: $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/*.html technical/api-index.txt + $(RM) SubmittingPatches.txt $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) manpage-base-url.xsl @@ -362,6 +364,9 @@ technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt +SubmittingPatches.txt: SubmittingPatches + $(QUIET_GEN) cp $< $@ + XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 558d465b65..33fa7a3013 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,40 +1,47 @@ +Submitting Patches +== + +== Guidelines + Here are some guidelines for people who want to contribute their code to this software. -(0) Decide what to base your work on. +[[base-branch]] +=== Decide what to base your work on. In general, always base your work on the oldest branch that your change is relevant to. - - A bugfix should be based on 'maint' in general. If the bug is not - present in 'maint', base it on 'master'. For a bug that's not yet - in 'master', find the topic that introduces the regression, and - base your work on the tip of the topic. +* A bugfix should be based on `maint` in general. If the bug is not + present in `maint`, base it on `master`. For a bug that's not yet + in `master`, find the topic that introduces the regression, and + base your work on the tip of the topic. - - A new feature should be based on 'master' in general. If the new - feature depends on a topic that is in 'pu', but not in 'master', - base your work on the tip of that topic. +* A new feature should be based on `master` in general. If the new + feature depends on a topic that is in `pu`, but not in `master`, + base your work on the tip of that topic. - - Corrections and enhancements to a topic not yet in 'master' should - be based on the tip of that topic. If the topic has not been merged - to 'next', it's alright to add a note to squash minor corrections - into the series. +* Corrections and enhancements to a topic not yet in `master` should + be based on the tip of that topic. If the topic has not been merged + to `next`, it's alright to add a note to squash minor correc
