docs: clarify rules wrt tagging other people

Point out that explicit permission is usually needed to tag other people
in changes, but mention that implicit permission can be sufficient in
certain ca

docs: clarify rules wrt tagging other people

Point out that explicit permission is usually needed to tag other people
in changes, but mention that implicit permission can be sufficient in
certain cases. This fixes slight inconsistencies between Reported-by:
and Suggested-by: and makes the usage more intuitive.

While at it, explicitly mention the dangers of our bugzilla instance, as
it makes it easy to forget that email addresses visible there are only
shown to logged-in users.

The latter is not a theoretical issue, as one maintainer mentioned that
his employer received a EU GDPR (general data protection regulation)
complaint after exposing a email address used in bugzilla through a tag
in a patch description.

Cc: Laurent Pinchart <[email protected]>
Cc: Simona Vetter <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Cc: Greg Kroah-Hartman <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Shuah Khan <[email protected]>
Signed-off-by: Thorsten Leemhuis <[email protected]>
Reviewed-by: Laurent Pinchart <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/588cf2763baa8fea1f4825f4eaa7023fe88bb6c1.1738852082.git.linux@leemhuis.info

show more ...

docs: 5.Posting: mentioned Suggested-by: tag

Mention the Suggested-by: tag in 5.Posting.rst in a way similar to
submitting-patches.rst, which according to the header of the latter is
the less detail

docs: 5.Posting: mentioned Suggested-by: tag

Mention the Suggested-by: tag in 5.Posting.rst in a way similar to
submitting-patches.rst, which according to the header of the latter is
the less detailed document of the two.

Reviewed-by: Greg Kroah-Hartman <[email protected]>
Signed-off-by: Thorsten Leemhuis <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/fbebad6605b02e372b24c2cfa1e05f789fed43d1.1733127086.git.linux@leemhuis.info

show more ...

docs: remove Documentation/dontdiff

The dontdiff file is a relic from the pre-Git era that has little use now.
It has entries (parse.c, for example) that will mask real changes to kernel
source file

docs: remove Documentation/dontdiff

The dontdiff file is a relic from the pre-Git era that has little use now.
It has entries (parse.c, for example) that will mask real changes to kernel
source files. There are all kinds of entries for files we do not create
anymore. Rather than try to fix it up, simply remove it.

Update the kernel documentation (and translations) to remove references to
this file. There is an ancient Japanese translation of SubmittingPatches
that I am unable to update; that really needs a thorough redo.

Message-ID: <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: process: allow Closes tags with links

Since v6.3, checkpatch.pl now complains about the use of "Closes:" tags
followed by a link [1]. It also complains if a "Reported-by:" tag is
followed by

docs: process: allow Closes tags with links

Since v6.3, checkpatch.pl now complains about the use of "Closes:" tags
followed by a link [1]. It also complains if a "Reported-by:" tag is
followed by a "Closes:" one [2].

As detailed in the first patch, this "Closes:" tag is used for a bit of
time, mainly by DRM and MPTCP subsystems. It is used by some bug trackers
to automate the closure of issues when a patch is accepted. It is even
planned to use this tag with bugzilla.kernel.org [3].

The first patch updates the documentation to explain what is this
"Closes:" tag and how/when to use it. The second patch modifies
checkpatch.pl to stop complaining about it.

The DRM maintainers and their mailing list have been added in Cc as they
are probably interested by these two patches as well.

[1] https://lore.kernel.org/all/3b036087d80b8c0e07a46a1dbaaf4ad0d018f8d5.1674217480.git.linux@leemhuis.info/
[2] https://lore.kernel.org/all/bb5dfd55ea2026303ab2296f4a6df3da7dd64006.1674217480.git.linux@leemhuis.info/
[3] https://lore.kernel.org/linux-doc/[email protected]/


This patch (of 5):

Making sure a bug tracker is up to date is not an easy task. For example,
a first version of a patch fixing a tracked issue can be sent a long time
after having created the issue. But also, it can take some time to have
this patch accepted upstream in its final form. When it is done, someone
-- probably not the person who accepted the patch -- has to remember about
closing the corresponding issue.

This task of closing and tracking the patch can be done automatically by
bug trackers like GitLab [1], GitHub [2] and hopefully soon [3]
bugzilla.kernel.org when the appropriated tag is used. The two first ones
accept multiple tags but it is probably better to pick one.

According to commit 76f381bb77a0 ("checkpatch: warn when unknown tags are used for links"),
the "Closes" tag seems to have been used in the past by a few people and
it is supported by popular bug trackers. Here is how it has been used in
the past:

$ git log --no-merges --format=email -P --grep='^Closes: http' | \
grep '^Closes: http' | cut -d/ -f3-5 | sort | uniq -c | sort -rn
391 gitlab.freedesktop.org/drm/intel
79 github.com/multipath-tcp/mptcp_net-next
8 gitlab.freedesktop.org/drm/msm
3 gitlab.freedesktop.org/drm/amd
2 gitlab.freedesktop.org/mesa/mesa
1 patchwork.freedesktop.org/series/73320
1 gitlab.freedesktop.org/lima/linux
1 gitlab.freedesktop.org/drm/nouveau
1 github.com/ClangBuiltLinux/linux
1 bugzilla.netfilter.org/show_bug.cgi?id=1579
1 bugzilla.netfilter.org/show_bug.cgi?id=1543
1 bugzilla.netfilter.org/show_bug.cgi?id=1436
1 bugzilla.netfilter.org/show_bug.cgi?id=1427
1 bugs.debian.org/625804

Likely here, the "Closes" tag was only properly used with GitLab and
GitHub. We can also see that it has been used quite a few times (and
still used recently) and this is then not a "random tag that makes no
sense" like it was the case with "BugLink" recently [4]. It has also been
misused but that was a long time ago, when it was common to use many
different random tags.

checkpatch.pl script should then stop complaining about this "Closes" tag.
As suggested by Thorsten [5], if this tag is accepted, it should first be
described in the documentation. This is what is done here in this patch.

To avoid confusion, the "Closes" should be used with any public bug
report. No need to check if the underlying bug tracker supports
automations. Having this tag with any kind of public bug reports allows
bots like regzbot to clearly identify patches fixing a specific bug and
avoid false-positives, e.g. patches mentioning it is related to an issue
but not fixing it. As suggested by Thorsten [6] again, if we follow the
same logic, the "Closes" tag should then be used after a "Reported-by"
one.

Note that thanks to this "Closes" tag, the mentioned bug trackers can also
locate where a patch has been applied in different branches and
repositories. If only the "Link" tag is used, the tracking can also be
done but the ticket will not be closed and a manual operation will be
needed. Also, these bug trackers have some safeguards: the closure is
only done if a commit having the "Closes:" tag is applied in a specific
branch. It will then not be closed if a random commit having the same tag
is published elsewhere. Also in case of closure, a notification is sent
to the owners.

Link: https://lkml.kernel.org/r/20230314-doc-checkpatch-closes-tag-v4-0-d26d1fa66f9f@tessares.net
Link: https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#default-closing-pattern [1]
Link: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests [2]
Link: https://lore.kernel.org/linux-doc/[email protected]/ [3]
Link: https://lore.kernel.org/all/CAHk-=wgs38ZrfPvy=nOwVkVzjpM3VFU1zobP37Fwd_h9iAD5JQ@mail.gmail.com/ [4]
Link: https://lore.kernel.org/all/[email protected]/ [5]
Link: https://lore.kernel.org/linux-doc/[email protected]/ [6]
Link: https://github.com/multipath-tcp/mptcp_net-next/issues/373
Link: https://lkml.kernel.org/r/20230314-doc-checkpatch-closes-tag-v4-1-d26d1fa66f9f@tessares.net
Signed-off-by: Matthieu Baerts <[email protected]>
Suggested-by: Thorsten Leemhuis <[email protected]>
Acked-by: Konstantin Ryabitsev <[email protected]>
Acked-by: Joe Perches <[email protected]>
Cc: Andy Whitcroft <[email protected]>
Cc: Bagas Sanjaya <[email protected]>
Cc: Daniel Vetter <[email protected]>
Cc: David Airlie <[email protected]>
Cc: Dwaipayan Ray <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Kai Wasserbäch <[email protected]>
Cc: Linus Torvalds <[email protected]>
Cc: Lukas Bulwahn <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>

show more ...

docs: recommend using Link: whenever using Reported-by:

Encourage developers to place Link: tag pointing to the report when they
are using Reported-by: tags. Those links are often extremely useful f

docs: recommend using Link: whenever using Reported-by:

Encourage developers to place Link: tag pointing to the report when they
are using Reported-by: tags. Those links are often extremely useful for
any code archaeologist that wants to know more about the backstory of a
change than the commit message provides. That includes maintainers
higher up in the patch-flow hierarchy, which is why Linus asks
developers to add such links [1, 2, 3]. To quote [1]:

> Again, the commit has a link to the patch *submission*, which is
> almost entirely useless. There's no link to the actual problem the
> patch fixes.
>
> [...]
>
> Put another way: I can see that
>
> Reported-by: Zhangfei Gao <[email protected]>
>
> in the commit, but I don't have a clue what the actual report was, and
> there really isn't enough information in the commit itself, except for
> a fairly handwavy "Device drivers might, for instance, still need to
> flush operations.."
>
> I don't want to know what device drivers _might_ do. I would want to
> have an actual pointer to what they do and where.

Another reason why these links are wanted: the ongoing regression
tracking efforts can only scale with them, as they allow the regression
tracking bot 'regzbot' to automatically connect tracked reports with
patches that are posted or committed to fix tracked regressions.

Link: https://lore.kernel.org/all/CAHk-=wjMmSZzMJ3Xnskdg4+GGz=5p5p+GSYyFBTh0f-DgvdBWg@mail.gmail.com/ [1]
Link: https://lore.kernel.org/all/CAHk-=wgs38ZrfPvy=nOwVkVzjpM3VFU1zobP37Fwd_h9iAD5JQ@mail.gmail.com/ [2]
Link: https://lore.kernel.org/all/CAHk-=wjxzafG-=J8oT30s7upn4RhBs6TX-uVFZ5rME+L5_DoJA@mail.gmail.com/ [3]
Signed-off-by: Thorsten Leemhuis <[email protected]>
Link: https://lore.kernel.org/r/9a07ec640d809723492f8ade4f54705914e80419.1676369564.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: process/5.Posting.rst: clarify use of Reported-by: tag

Bring the description on when to use the Reported-by: tag found in
Documentation/process/5.Posting.rst more in line with the description

docs: process/5.Posting.rst: clarify use of Reported-by: tag

Bring the description on when to use the Reported-by: tag found in
Documentation/process/5.Posting.rst more in line with the description in
Documentation/process/submitting-patches.rst: before this change the two
were contradicting each other, as the latter is way more permissive and
only states '[...] if the bug was reported in private, then ask for
permission first before using the Reported-by tag.'

Signed-off-by: Thorsten Leemhuis <[email protected]>
Link: https://lore.kernel.org/r/2fc7162dfb76e04da5ea903c9c170d913e735dad.1664372256.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: process: remove outdated submitting-drivers.rst

Commit 31b24bee3357 ("docs: add a warning to submitting-drivers.rst")
in October 2016 already warns "This (...) should maybe just be deleted,
bu

docs: process: remove outdated submitting-drivers.rst

Commit 31b24bee3357 ("docs: add a warning to submitting-drivers.rst")
in October 2016 already warns "This (...) should maybe just be deleted,
but I'm not quite ready to do that yet".

Maybe, six years ago, we were not ready but let us remove old content
for the better now and structure and maintain less content in the kernel
documentation with a better result.

Drop this already outdated document and adjust all textual references.

Here is an argument why deleting the content will not remove any useful
information to the existing kernel documentation, individually broken down
for each section.

Section "Allocating Device Numbers" refers to https://www.lanana.org/, and
then refers to Documentation/admin-guide/devices.rst.

However, the devices.rst clearly states:

"The version of this document at lanana.org is no longer maintained."

Everything needed for submitting drivers is already stated in devices.rst
and the reference to https://www.lanana.org/ is outdated, and should be
just deleted.

Section "Who To Submit Drivers To" is all about Linux 2.0 - 2.6, before
the new release version scheme; the mentioned developers are still around,
but actually not the first developers to contact anymore.

Section "What Criteria Determine Acceptance" has a few bullet points:

Licensing and Copyright is well-covered in process/kernel-license.rst.

Interfaces, Code, Portability, Clarity state some obvious things about
ensuring kernel code quality.

Control suggests to add a MAINTAINERS entry, which is already mentioned in
6.Followthrough.rst: "... added yourself to the MAINTAINERS file..."

PM support states a bit about implementing and testing power management of
a driver, it remains an open question where to place that in the process
documents. Driver developers interested in power management will find the
corresponding part on power management in the kernel documentation anyway.

In section "What Criteria Do Not Determine Acceptance", the points Vendor
and Author states something basic consequence of the kernel being an
open-source community software development. Probably no need to mention it
nowadays.

Section "Resources" lists resources that are also mentioned elsewhere more
central.

- Linux kernel tree and mailing list is mentioned in many places.
- https://lwn.net/Kernel/LDD3/ is mentioned in
Documentation/process/kernel-docs.rst.

- https://lwn.net/ is mentioned in:
- Documentation/process/8.Conclusion.rst
- Documentation/process/kernel-docs.rst

- https://kernelnewbies.org/ is mentioned in:
- Documentation/process/8.Conclusion.rst
- Documentation/process/kernel-docs.rst

- http://www.linux-usb.org/ is mentioned in
Documentation/driver-api/usb/usb.rst

- https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
is mentioned in Documentation/process/kernel-docs.rst

- https://kernelnewbies.org/KernelJanitors is mentioned in
Documentation/process/howto.rst

- https://git-scm.com/ is mentioned in
- Documentation/process/2.Process.rst
- Documentation/process/7.AdvancedTopics.rst
- Documentation/process/howto.rst

Signed-off-by: Lukas Bulwahn <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: 5.Posting.rst: describe Fixes: and Link: tags

Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
which are missing in this file for unknown reasons and only described in
Doc

docs: 5.Posting.rst: describe Fixes: and Link: tags

Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
which are missing in this file for unknown reasons and only described in
Documentation/process/submitting-patches.rst.

Signed-off-by: Thorsten Leemhuis <[email protected]>
CC: Konstantin Ryabitsev <[email protected]>
Link: https://lore.kernel.org/r/c4a5f5e25fa84b26fd383bba6eafde4ab57c9de7.1641314856.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Clarify the usage and sign-off requirements for Co-developed-by

The documentation for Co-developed-by is a bit light on details, e.g. it
doesn't explicitly state that:

- Multiple Co-develop

docs: Clarify the usage and sign-off requirements for Co-developed-by

The documentation for Co-developed-by is a bit light on details, e.g. it
doesn't explicitly state that:

- Multiple Co-developed-by tags are perfectly acceptable
- Co-developed-by and Signed-off-by must be paired together
- SOB ordering should still follow standard sign-off procedure

Lack of explicit direction has resulted in developers taking a variety
of approaches, often lacking any intent whatsoever, e.g. scattering SOBs
willy-nilly, collecting them all at the end or the beginning, etc...
Tweak the wording to make it clear that multiple co-authors are allowed,
and document the expectation that standard sign-off procedures are to
be followed.

The use of "original author" has also led to confusion as many patches
don't have just one "original" author, e.g. when multiple developers
are involved from the genesis of the patch. Remove all usage of
"original" and instead call out that Co-developed-by is simply a way to
provide attribution in addition to the From tag, i.e. neither tag is
intended to imply anything with regard to who did what.

Provide examples to (hopefully) eliminate any ambiguity.

Cc: Tobin C. Harding <[email protected]>
Cc: Thomas Gleixner <[email protected]>
Cc: Jani Nikula <[email protected]>
Cc: Jorge Ramirez-Ortiz <[email protected]>
Cc: Jonathan Cameron <[email protected]>
Cc: Joe Perches <[email protected]>
Cc: Greg Kroah-Hartman <[email protected]>
Cc: Niklas Cassel <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Sean Christopherson <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

doc:process: add links where missing

Some documents are refering to others without links. With this
patch I add those missing links.

This patch affects only documents under process/ and labels wher

doc:process: add links where missing

Some documents are refering to others without links. With this
patch I add those missing links.

This patch affects only documents under process/ and labels where
necessary.

Signed-off-by: Federico Vaga <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation/process/posting: wrap text at 80 cols

Trivial patch to adjust the text formatting to wrap at 80 columns. No
actual content has changed.

Signed-off-by: Justin Skists <justin.skists@juz

Documentation/process/posting: wrap text at 80 cols

Trivial patch to adjust the text formatting to wrap at 80 columns. No
actual content has changed.

Signed-off-by: Justin Skists <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation/process: Co-developed-by instead of Co-Developed-by

Up to now, all commit messages have used the "d" in lower case.

Signed-off-by: Dominik Brodowski <[email protected]>
Signe

Documentation/process: Co-developed-by instead of Co-Developed-by

Up to now, all commit messages have used the "d" in lower case.

Signed-off-by: Dominik Brodowski <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation/process: add Co-Developed-by: tag for patches with multiple authors

Sometimes a single patch is the result of multiple authors. As git only
can have one "author" of a patch, it is sti

Documentation/process: add Co-Developed-by: tag for patches with multiple authors

Sometimes a single patch is the result of multiple authors. As git only
can have one "author" of a patch, it is still good to properly give
credit to the other developers of a commit. To address this, document
the "Co-Developed-by:" tag which can be used to show other authors of
the patch.

Note, these other authors must also provide a Signed-off-by: tag as it
is their work that is being submitted here.

Reported-by: Thomas Gleixner <[email protected]>
Signed-off-by: Greg Kroah-Hartman <[email protected]>
Reviewed-by: Thomas Gleixner <[email protected]>
Acked-by: Borislav Petkov <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: fix locations of several documents that got moved

The previous patch renamed several files that are cross-referenced
along the Kernel documentation. Adjust the links to point to
the right plac

docs: fix locations of several documents that got moved

The previous patch renamed several files that are cross-referenced
along the Kernel documentation. Adjust the links to point to
the right places.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...

docs: rename development-process/ to process/

As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.

Signed-off-by: Mauro Carvalho Chehab <m

docs: rename development-process/ to process/

As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...