Re: Re*: [PATCH v9] Documentation/remote-helpers: Add invocation section

[Michael J Gruber <git@drmicha.warpmail.net>]

Junio C Hamano venit, vidit, dixit 09.04.2010 04:01:
> Sverre Rabbelier <srabbelier@gmail.com> writes:
> 
>> Hmmm, perhaps we should update SubmittingPatches to say something
>> about that? The section that talks about what to base your patch
>> against is not very explicit in that aspect.
> 
> Ok, here is a rough draft.
> 
>  Documentation/SubmittingPatches |   52 ++++++++++++++++++++++++++++++--------
>  1 files changed, 41 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index c686f86..1d403ee 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -53,6 +53,37 @@ But the patch submission requirements are a lot more relaxed
>  here on the technical/contents front, because the core GIT is
>  thousand times smaller ;-).  So here is only the relevant bits.
>  
> +(0) Decide what to base your work on.
> +
> +The general principle is always to base your work on the oldest branch
> +that your change is relevant to.
> +
> + - A fix for a bug that has been with git from older releases should be
> +   included in both the upcoming feature release and the current
> +   maintenance release.  Try to base your work on the 'maint' branch.  A
> +   work to kill a bug that is in 'master' but not in 'maint' should be
> +   based on 'master'.
> +
> + - A fix for a bug that is not yet in 'master' is the best bug to kill.
> +   If you can find the topic that introduces the regression, base your
> +   work on the tip of the topic.  "log --first-parent master..pu" would be
> +   a good way to find the tips of topic branches.
> +
> + - A new feature should be based on the 'master' branch in general.
> +
> + - If your new feature depends on some other topics that are not in
> +   'master' yet, and if it relies only on one topic, base your work on the
> +   tip of that topic.  If it depends on too many topics that are not in
> +   'master', you can privately start working on 'next' or even 'pu' and
> +   send out your patches for discussion, but it is possible that your
> +   maintainer may ask you to wait and rebase your changes on 'master'
> +   after some of the larger topics your topic depends on graduate to
> +   'master'.
> +
> + - Base corrections and enhancements on a topic that are not in 'master'
> +   yet but already merged to 'next' on the tip of the topic.  If the topic
> +   has not been merged to 'next', it is Ok to add a note that the patch is
> +   a trivial fix and can be squashed into the series.
>  
>  (1) Make separate commits for logically separate changes.
>  
> @@ -170,17 +201,16 @@ patch, format it as "multipart/signed", not a text/plain message
>  that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
>  not a text/plain, it's something else.
>  
> -Note that your maintainer does not necessarily read everything
> -on the git mailing list.  If your patch is for discussion first,
> -send it "To:" the mailing list, and optionally "cc:" him.  If it
> -is trivially correct or after the list reached a consensus, send
> -it "To:" the maintainer and optionally "cc:" the list for
> -inclusion.
> -
> -Also note that your maintainer does not actively involve himself in
> -maintaining what are in contrib/ hierarchy.  When you send fixes and
> -enhancements to them, do not forget to "cc: " the person who primarily
> -worked on that hierarchy in contrib/.
> +Unless your patch is a very trivial and an obviously correct one,
> +first send it 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
> +identify them), to solicit comments and reviews.  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 and optionally "cc:" the list for
> +inclusion.  Do not forget to add trailers such as "Acked-by:",
> +"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
> +necessary.

I'm wondering how necessary that flipping of to and cc is. It means one
has to switch one's send-email config between RFCs and actual patches.
It also means I should send fewer patches to you (Junio) directly (in
addition to cc'ing the list), which is probably the intention :)
OK, I've learned about aliasesfile (and wondered about the different
wording compared to aliasfiletype) meanwhile, so no problem...

>  
>  
>  (4) Sign your work