[FFmpeg-devel] [PATCH v1 2/3] doc/developer.texi: Restructured "Submitting patches" section.

[Manolis Stamatogiannakis]

On Tue, 7 Jul 2020 at 16:07, Nicolas George <george at nsup.org> wrote:

> Manolis Stamatogiannakis (12020-07-05):
>
> > + at item If you send your patches with an external email client
> > +(i.e. not @code{git send-email}), make sure to send each patch as a
> separate
> > +email. Do not attach several patches to the same email!
>
> This is a new rule, it did not exist before, and I see little value in
> it except making Patchwork happy.
>


The current documentation mentions:
L1: Also please do not submit a patch which contains several unrelated
changes.
...
L2: Also please if you send several patches, send each patch as a separate
mail, do not attach several unrelated patches to the same mail.
...
L3: Use git send-email when possible since it will properly send patches
without requiring extra care.

The rule in the list is a summary of these three lines.
I may have interpreted them wrong, as there's a slight overlap (L1-L2: they
look the same) and a slight conflict (L2-L3: git send-email sends one email
per commit, not per patch).

Since you send your patches with an external email client, can you come up
with a better/more accurate phrasing based on your workflow?



> >
> > -Run the @ref{Regression tests} before submitting a patch in order to
> verify
> > -it does not cause unexpected problems.
> > + at item Do not submit a patch which contains several unrelated changes.
> > + at end enumerate
> > +
>
> > +Additionally, it is also important that the commits comprising a patch
> > +are logically self-contained. I.e. each commit should be as small as
>
> Uh? Are you making a distinction between commits and patches? So, can we
> have a single patch with several commits in one mail?
>
> Or maybe the accurate wording is just not consistent.
>

I believe that much of the wording in developer.html stems from the svn
days, so it reads a bit funny if you've been using git exclusively for 5+
years.
Here are the number of lines committed per year in developer.texi:
2014: 3
2018: 8
2012: 21
2015: 29
2017: 50
2016: 86
2011: 105
2020: 124
2009: 127
2013: 351

So let's stick with "patches" and forget about commits for now. Does this
sound better?

"Additionally, it is also important that each patch is logically
self-contained.
I.e. each patch should be as small as possible while still containing a
meaningful
individual change.
Patches spanning multiple files are perfectly fine, as long as they can be
seen
as a single logical unit."


Thanks for the review!

Best regards,
Manolis