Contributors

Posted Sep 8, 2024 12:14 UTC (Sun) by alx.manpages (subscriber, #145117)
In reply to: Contributors by intelfx
Parent article: Man pages maintenance suspended

> and if you're the reviewer, reading code and docs at the same time might help you to spot inconsistencies which typically mean some cases were not considered by the author.

That's precisely how it's done. The patches being to separate git repositories doesn't mean that they must be in separate mail threads.

See an example of a kernel feature and its documentation being reviewed at the same time, and by all parties, here:
<https://lore.kernel.org/linux-man/CAEf4BzZzE94QUdhWPmrMzR...>

And for libc, it would also be great if developers would include a man-pages patch at the same time they work on a libc feature, and send both the libc and man-pages patches in the same mail thread, for a better review.

Maybe this should be documented in the contribution guidelines of the man-pages project.

Contributors

Posted Sep 8, 2024 13:06 UTC (Sun) by gnoack (subscriber, #131611) [Link] (2 responses)

Oh, thanks, I had no idea this was even possible with git format-patch! o_O. I agree, we should absolutely start using that process (once the maintenance situation is resolved).

IMHO this should not just go into the man-pages documentation, but also in the kernel contribution documentation.

Is there a recommended way to produce such patch sets, and to mail them, other than manipulating the generated mails themselves? Are there special tools that people use which I overlooked? :)

Thanks,
—Günther

Contributors

Posted Sep 8, 2024 13:55 UTC (Sun) by alx.manpages (subscriber, #145117) [Link] (1 responses)

`git format-patch --thread=shallow` is what you're looking for.

```
--thread[=<style>], --no-thread
Controls addition of In-Reply-To and References headers to
make the second and subsequent mails appear as replies to the
first. Also controls generation of the Message-ID header to
reference.
```

That will generate a Message-ID in the cover letter when you generate the kernel patch set. When you generate the patch set for the man pages, just use `--in-reply-to="<the_message_id_of_the_cover_letter>"`.

I don't know if there's a better way to do it. This one looks simple to me. You may want to also tweak the patch numbers, which I think you'll need to do manually (at least some part), but you could use separate numbering as well, which I think is fine, and wouldn't require manual tweaks. Maybe Jiri can explain another approach.

Contributors

Posted Sep 9, 2024 7:22 UTC (Mon) by gnoack (subscriber, #131611) [Link]

FWIW, I believe I found a way that might be better:

Import multiple projects into the same local repository.

This is a bit unusual, but you can actually just git fetch multiple unrelated repositories at once.

In my example, I used worktrees to make my file system layout look a bit more conventional -- have one worktree under /tmp/proj and one under /tmp/man. For the sake of the example, I'll assume that they are checked out to same-named branches "proj" and "man".
Now you can format a patch set using:
```
git format-patch --cover-letter --subject-prefix="PATCH proj" proj^^..proj man^..man
```
This results in a single patch set that includes both the project and man page patches.

Caveats:
- May need to control order of patches a bit better. Setting a newer timestamp on the man page patches seems to order them to the end, though.
- The subject prefix is still the same for all commits, those need to be edited by hand for the man page commits. Not sure whether there is a better way.

Maybe this is what Jiri used?