Enhance documentation for new developers

[PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Pierrick Bouvier 5 days ago

Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
---
 docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
index 349c32ee3a9..953682f20cb 100644
--- a/docs/devel/submitting-a-patch.rst
+++ b/docs/devel/submitting-a-patch.rst
@@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
 
 .. _if_you_cannot_send_patch_emails:
 
+Use git-publish
+~~~~~~~~~~~~~~~
+
+If you already configured git send-email, you can simply use `git-publish
+<https://github.com/stefanha/git-publish>`__ to send series.
+
+::
+
+    $ git checkout master -b my-feature
+    $ # work on new commits, add your 'Signed-off-by' lines to each
+    $ git publish
+    $ ... more work, rebase on master, ...
+    $ git publish # will send a v2
+
 If you cannot send patch emails
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.39.5

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Daniel P. Berrangé 4 days, 9 hours ago

On Mon, Nov 18, 2024 at 09:23:52AM -0800, Pierrick Bouvier wrote:
> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> ---
>  docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
> index 349c32ee3a9..953682f20cb 100644
> --- a/docs/devel/submitting-a-patch.rst
> +++ b/docs/devel/submitting-a-patch.rst
> @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
>  
>  .. _if_you_cannot_send_patch_emails:

This needs to remain associated with the heading that is *after*
your new block of text, while here you need to add a new anchor

   .. _use_git_publish:

>  
> +Use git-publish
> +~~~~~~~~~~~~~~~
> +
> +If you already configured git send-email, you can simply use `git-publish
> +<https://github.com/stefanha/git-publish>`__ to send series.
> +
> +::
> +
> +    $ git checkout master -b my-feature
> +    $ # work on new commits, add your 'Signed-off-by' lines to each
> +    $ git publish
> +    $ ... more work, rebase on master, ...
> +    $ git publish # will send a v2

Also add a note

 "Each time you post a series, git-publish will create a local tag
  with the format ``<branchname>-v<version>`` to record the patch
  series."

> +
>  If you cannot send patch emails
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -- 
> 2.39.5
> 

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Pierrick Bouvier 2 days, 20 hours ago

On 11/19/24 01:04, Daniel P. Berrangé wrote:
> On Mon, Nov 18, 2024 at 09:23:52AM -0800, Pierrick Bouvier wrote:
>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
>> ---
>>   docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
>>   1 file changed, 14 insertions(+)
>>
>> diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
>> index 349c32ee3a9..953682f20cb 100644
>> --- a/docs/devel/submitting-a-patch.rst
>> +++ b/docs/devel/submitting-a-patch.rst
>> @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
>>   
>>   .. _if_you_cannot_send_patch_emails:
> 
> This needs to remain associated with the heading that is *after*
> your new block of text, while here you need to add a new anchor
> 

Oops, that was not intentional, thanks for pointing this.
Fixed and added the new anchor in case someone needs it.

>     .. _use_git_publish:
> 
>>   
>> +Use git-publish
>> +~~~~~~~~~~~~~~~
>> +
>> +If you already configured git send-email, you can simply use `git-publish
>> +<https://github.com/stefanha/git-publish>`__ to send series.
>> +
>> +::
>> +
>> +    $ git checkout master -b my-feature
>> +    $ # work on new commits, add your 'Signed-off-by' lines to each
>> +    $ git publish
>> +    $ ... more work, rebase on master, ...
>> +    $ git publish # will send a v2
> 
> Also add a note
> 
>   "Each time you post a series, git-publish will create a local tag
>    with the format ``<branchname>-v<version>`` to record the patch
>    series."
> 

Added this 👍.

>> +
>>   If you cannot send patch emails
>>   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   
>> -- 
>> 2.39.5
>>
> 
> With regards,
> Daniel

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Marcin Juszkiewicz 4 days, 9 hours ago

W dniu 18.11.2024 o 18:23, Pierrick Bouvier pisze:
> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> ---
>   docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
>   1 file changed, 14 insertions(+)
> 
> diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
> index 349c32ee3a9..953682f20cb 100644
> --- a/docs/devel/submitting-a-patch.rst
> +++ b/docs/devel/submitting-a-patch.rst
> @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
>   
>   .. _if_you_cannot_send_patch_emails:
>   
> +Use git-publish
> +~~~~~~~~~~~~~~~
> +
> +If you already configured git send-email, you can simply use `git-publish
> +<https://github.com/stefanha/git-publish>`__ to send series.
> +
> +::
> +
> +    $ git checkout master -b my-feature
> +    $ # work on new commits, add your 'Signed-off-by' lines to each
> +    $ git publish
> +    $ ... more work, rebase on master, ...
> +    $ git publish # will send a v2

You recommend 'b4 shazam' in 3/7 patch so why not here? Both 'b4' and 
'git-publish' seem to do same stuff - handle patch series and send them 
upstream.

b4 allows to keep To/Cc emails inside of cover letter which makes it 
easy to not miss anyone needed.

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Pierrick Bouvier 3 days, 11 hours ago

On 11/19/24 00:41, Marcin Juszkiewicz wrote:
> W dniu 18.11.2024 o 18:23, Pierrick Bouvier pisze:
>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
>> ---
>>    docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
>>    1 file changed, 14 insertions(+)
>>
>> diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
>> index 349c32ee3a9..953682f20cb 100644
>> --- a/docs/devel/submitting-a-patch.rst
>> +++ b/docs/devel/submitting-a-patch.rst
>> @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
>>    
>>    .. _if_you_cannot_send_patch_emails:
>>    
>> +Use git-publish
>> +~~~~~~~~~~~~~~~
>> +
>> +If you already configured git send-email, you can simply use `git-publish
>> +<https://github.com/stefanha/git-publish>`__ to send series.
>> +
>> +::
>> +
>> +    $ git checkout master -b my-feature
>> +    $ # work on new commits, add your 'Signed-off-by' lines to each
>> +    $ git publish
>> +    $ ... more work, rebase on master, ...
>> +    $ git publish # will send a v2
> 
> You recommend 'b4 shazam' in 3/7 patch so why not here? Both 'b4' and
> 'git-publish' seem to do same stuff - handle patch series and send them
> upstream.
>

Are you using b4 for your QEMU contributions?

When I started working on QEMU, I tried it before git-publish and had an 
error when trying to send my series. I don't remember exactly what it 
was, but something related to finding the reviewers for a given commit. 
When I asked, team members pointed me towards git-publish.

> b4 allows to keep To/Cc emails inside of cover letter which makes it
> easy to not miss anyone needed.

git-publish works pretty well for me, and does what you expect (keep 
your cover letter/cc and track your versions).

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Alex Bennée 3 days, 8 hours ago

Pierrick Bouvier <pierrick.bouvier@linaro.org> writes:

> On 11/19/24 00:41, Marcin Juszkiewicz wrote:
>> W dniu 18.11.2024 o 18:23, Pierrick Bouvier pisze:
>>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
>>> ---
>>>    docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
>>>    1 file changed, 14 insertions(+)
>>>
>>> diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
>>> index 349c32ee3a9..953682f20cb 100644
>>> --- a/docs/devel/submitting-a-patch.rst
>>> +++ b/docs/devel/submitting-a-patch.rst
>>> @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
>>>       .. _if_you_cannot_send_patch_emails:
>>>    +Use git-publish
>>> +~~~~~~~~~~~~~~~
>>> +
>>> +If you already configured git send-email, you can simply use `git-publish
>>> +<https://github.com/stefanha/git-publish>`__ to send series.
>>> +
>>> +::
>>> +
>>> +    $ git checkout master -b my-feature
>>> +    $ # work on new commits, add your 'Signed-off-by' lines to each
>>> +    $ git publish
>>> +    $ ... more work, rebase on master, ...
>>> +    $ git publish # will send a v2
>> You recommend 'b4 shazam' in 3/7 patch so why not here? Both 'b4'
>> and
>> 'git-publish' seem to do same stuff - handle patch series and send them
>> upstream.
>>
>
> Are you using b4 for your QEMU contributions?
>
> When I started working on QEMU, I tried it before git-publish and had
> an error when trying to send my series. I don't remember exactly what
> it was, but something related to finding the reviewers for a given
> commit. When I asked, team members pointed me towards git-publish.

I tend to use b4 to apply patches because it works well with the
archives and collects together the tags for you. I have not used it to
publish patches to the list.

My sending workflow used done manually (rather via my carefully
customised Emacs org workflow) but now I just use git publish to send
series to the list. I still occasionally use git send-email directly for
sending individual patches with something like:

  git send-email --subject-prefix="RFC PATCH" --to qemu HEAD^..

I still send pull requests by hand:

  git send-email --confirm=never --quiet ${mailto} ${series}.pull/*

but thats probably because I haven't figured out the steps for git
publish to do that.

Anyway tldr; b4 to apply *from* list, git publish to send *to* list.

>
>> b4 allows to keep To/Cc emails inside of cover letter which makes it
>> easy to not miss anyone needed.
>
> git-publish works pretty well for me, and does what you expect (keep
> your cover letter/cc and track your versions).

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Daniel P. Berrangé 3 days, 8 hours ago

On Wed, Nov 20, 2024 at 09:51:27AM +0000, Alex Bennée wrote:
> 
> I still send pull requests by hand:
> 
>   git send-email --confirm=never --quiet ${mailto} ${series}.pull/*
> 
> but thats probably because I haven't figured out the steps for git
> publish to do that.

A one-time setup task is to tell it what you preferred git remote is.
I use "gitlab" as the name of my personal gitlab fork of QEMU, so 

  $ git config remote.pushDefault gitlab

With that one-time setup task, sending a pull rquest needs nothing more
than adding  '--pull' to the git-publish cli. It'll trigger signing of
the tag, so be sure you have your gpg key available, and then push both
the branch and signed tag to your git remote, and send emails in its
normal way.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Daniel P. Berrangé 4 days, 8 hours ago

On Tue, Nov 19, 2024 at 09:41:40AM +0100, Marcin Juszkiewicz wrote:
> W dniu 18.11.2024 o 18:23, Pierrick Bouvier pisze:
> > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> > ---
> >   docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
> >   1 file changed, 14 insertions(+)
> > 
> > diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
> > index 349c32ee3a9..953682f20cb 100644
> > --- a/docs/devel/submitting-a-patch.rst
> > +++ b/docs/devel/submitting-a-patch.rst
> > @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
> >   .. _if_you_cannot_send_patch_emails:
> > +Use git-publish
> > +~~~~~~~~~~~~~~~
> > +
> > +If you already configured git send-email, you can simply use `git-publish
> > +<https://github.com/stefanha/git-publish>`__ to send series.
> > +
> > +::
> > +
> > +    $ git checkout master -b my-feature
> > +    $ # work on new commits, add your 'Signed-off-by' lines to each
> > +    $ git publish
> > +    $ ... more work, rebase on master, ...
> > +    $ git publish # will send a v2
> 
> You recommend 'b4 shazam' in 3/7 patch so why not here? Both 'b4' and
> 'git-publish' seem to do same stuff - handle patch series and send them
> upstream.

git-publish is what we already recommended to people both elsewhere in
this file, and more prominently in the README.rst file, so maintaining
that practice is correct.

> b4 allows to keep To/Cc emails inside of cover letter which makes it easy to
> not miss anyone needed.

git-publish automatically CC's people by correlating the files touched in
the commits against our MAINTAINERS file, so it "does the right thing"
in the majority of cases. We recommend it because it makes it much harder
for novice users to mess up patch series submission.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 2/7] docs/devel: add git-publish for patch submitting

Posted by Pierrick Bouvier 3 days, 11 hours ago

On 11/19/24 01:12, Daniel P. Berrangé wrote:
> On Tue, Nov 19, 2024 at 09:41:40AM +0100, Marcin Juszkiewicz wrote:
>> W dniu 18.11.2024 o 18:23, Pierrick Bouvier pisze:
>>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
>>> ---
>>>    docs/devel/submitting-a-patch.rst | 14 ++++++++++++++
>>>    1 file changed, 14 insertions(+)
>>>
>>> diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
>>> index 349c32ee3a9..953682f20cb 100644
>>> --- a/docs/devel/submitting-a-patch.rst
>>> +++ b/docs/devel/submitting-a-patch.rst
>>> @@ -237,6 +237,20 @@ attachments can be used as a last resort on a first-time submission.
>>>    .. _if_you_cannot_send_patch_emails:
>>> +Use git-publish
>>> +~~~~~~~~~~~~~~~
>>> +
>>> +If you already configured git send-email, you can simply use `git-publish
>>> +<https://github.com/stefanha/git-publish>`__ to send series.
>>> +
>>> +::
>>> +
>>> +    $ git checkout master -b my-feature
>>> +    $ # work on new commits, add your 'Signed-off-by' lines to each
>>> +    $ git publish
>>> +    $ ... more work, rebase on master, ...
>>> +    $ git publish # will send a v2
>>
>> You recommend 'b4 shazam' in 3/7 patch so why not here? Both 'b4' and
>> 'git-publish' seem to do same stuff - handle patch series and send them
>> upstream.
> 
> git-publish is what we already recommended to people both elsewhere in
> this file, and more prominently in the README.rst file, so maintaining
> that practice is correct.
> 

At the time I started working on QEMU, I missed that information, 
because I focused on the manual (missing the content of the README), so 
that's why I add it here as well.

>> b4 allows to keep To/Cc emails inside of cover letter which makes it easy to
>> not miss anyone needed.
> 
> git-publish automatically CC's people by correlating the files touched in
> the commits against our MAINTAINERS file, so it "does the right thing"
> in the majority of cases. We recommend it because it makes it much harder
> for novice users to mess up patch series submission.
>

I agree with that. From my personal experience, the hardest part when 
onboarding with email workflow is more to understand it (which steps you 
go through until the contribution is accepted), more than learning a 
specific tool in particular.
So having a "simple" tool like git-publish is good.

> With regards,
> Daniel