IF YOU WOULD LIKE TO GET AN ACCOUNT, please write an
email to Administrator. User accounts are meant only to access repo
and report issues and/or generate pull requests.
This is a purpose-specific Git hosting for
BaseALT
projects. Thank you for your understanding!
Только зарегистрированные пользователи имеют доступ к сервису!
Для получения аккаунта, обратитесь к администратору.
In the second paragraph of section "Respond to review comments", there is
a spelling mistake: "aganst" should be "against".
Signed-off-by: Xujun Leng <lengxujun2007@126.com>
Link: https://lore.kernel.org/r/20230312071423.3042-1-lengxujun2007@126.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
but which I didn't get merged for the first round:
- A recommendation from Thorsten (also akpm) on use of Link tags to point
out problem reports.
- Some front-page formatting tweaks
- Another Spanish translation
- One typo(ish) fix.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmP+VoMPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5Y+FQIAIj1tmWwPkvzVlURhB9EKCSle91aZxvIZZR8
B8ibU3iak+TR5crkTzhjqy9VDRLv/LxgPVBdNzq6Wqz9phe0tReIdUcL30yIDKxP
KEaJZrdh58IyebVarpToLqKMZ0u5id/ettuvAJNCPDHWLAzud1oZXSh2eKJqfntb
eqLm+L+MkVpswDTN0HqXxxfDezM5zpfT3LOpX1+Fwg3/4JMy2QxoxIZewBnoKkI7
brgteTGVXxgmfemXtfGkFG9VzsszACzr86I24b+0sFXsXMgMGytEPjVZ9uSXspMw
8E3q63BokG/DxXeewvZwOCahaNRxPGkxX/GwKh9HNyEXdi6ooCw=
=xVak
-----END PGP SIGNATURE-----
Merge tag 'docs-6.3-2' of git://git.lwn.net/linux
Pull Documentation stragglers from Jonathan Corbet:
"A handful of documentation patches that were ready before the merge
window, but which I didn't get merged for the first round:
- A recommendation from Thorsten (also akpm) on use of Link tags to
point out problem reports
- Some front-page formatting tweaks
- Another Spanish translation
- One typo(ish) fix"
* tag 'docs-6.3-2' of git://git.lwn.net/linux:
docs: recommend using Link: whenever using Reported-by:
Documentation: front page: use recommended heading adornments
docs/sp_SP: Add process programming-language translation
docs: locking: refer to the actual existing config names
Long long ago, in a more innocent time, Greg wrote the clarification for
how the DCO should work and that you couldn't make anonymous
contributions, because the sign-off needed to be something we could
check back with.
It was 2006, and nobody reacted to the wording, the whole Facebook 'real
name' controversy was a decade in the future, and nobody even thought
about it. And despite the language, we've always accepted nicknames and
that language was never meant to be any kind of exclusionary wording.
In fact, even when it became a discussion in other adjacent projects,
apparently nobody even thought to just clarify the language in the
kernel docs, and instead we had projects like the CNCF that had long
discussions about it, and wrote their own clarifications [1] of it.
Just simplify the wording to the point where it shouldn't be causing
unnecessary angst and pain, or scare away people who go by preferred
naming.
Link: https://github.com/cncf/foundation/blob/659fd32c86dc/dco-guidelines.md [1]
Fixes: af45f32d25 ("We can not allow anonymous contributions to the kernel")
Acked-by: Greg KH <gregkh@linuxfoundation.org>
Acked-by: Michael Dolan <mdolan@linuxfoundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <zhangfei.gao@foxmail.com>
>
> 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 <linux@leemhuis.info>
Link: https://lore.kernel.org/r/9a07ec640d809723492f8ade4f54705914e80419.1676369564.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 31b24bee33 ("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 <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20220704122537.3407-7-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Explain that, when collecting list of people to Cc the patch,
scripts/get_maintainer.pl should be used on patches, not on the
directories. The behavior is quite different, because with "-f" on
a directory, the maintainers of individual files will not be shown.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Link: https://lore.kernel.org/r/20220427185645.677039-1-krzysztof.kozlowski@linaro.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The reference to `explicit_in_reply_to` is pointless as when the
reference was added in the form of "#15" [1], Section 15) was "The
canonical patch format".
The reference of "#15" had not been properly updated in a couple of
reorganizations during the plain-text SubmittingPatches era.
Fix it by using `the_canonical_patch_format`.
[1]: 2ae19acaa5 ("Documentation: Add "how to write a good patch summary" to SubmittingPatches")
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Fixes: 5903019b2a ("Documentation/SubmittingPatches: convert it to ReST markup")
Fixes: 9b2c76777a ("Documentation/SubmittingPatches: enrich the Sphinx output")
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: stable@vger.kernel.org # v4.9+
Link: https://lore.kernel.org/r/64e105a5-50be-23f2-6cae-903a2ea98e18@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Extend the "Respond to review comments" section of "Submitting patches"
with reference to patch changelogs.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It's unclear from "Submitting Patches" documentation that Reported-by
is not supposed to be used against new features. (It's more clear
in the section 5.4 "Patch formatting and changelogs" of the "A guide
to the Kernel Development Process", where it suggests that change
should fix something existing in the kernel. Clarify the Reported-by
usage in the "Submitting Patches".
Reported-by: Florian Eckert <fe@dev.tdt.de>
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220127163258.48482-1-andriy.shevchenko@linux.intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The cross-reference for the handbooks section works. However, it is
meant to describe the path inside the Kernel's doc where the section
is, but there's an space instead of a dash, plus it lacks the .rst at
the end, which makes:
./scripts/documentation-file-ref-check
to complain.
Fixes: 604370e106 ("Documentation/process: Add maintainer handbooks section")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mention the 'Link' tag in the section about adding URLs to the commit
msg, to make it clearer they "_primarily_ [...] should be about
background", as Linus recently stated (see the link below). That makes
the explanation also easier to find with a text search. For the same
reason and to improve comprehensibility provide an example, too.
Slightly improve the text at the same time to make it more obvious
developers are meant to add links to issue reports in mailing list
archives, as those allow regression tracking efforts to automatically
check which bugs got resolved.
Move the section also downwards slightly, to reduce jumping back and
forth between aspects relevant for the top and the bottom part of the
commit msg.
Link: https://lore.kernel.org/lkml/CAHk-=wgBhyLhQLPem1vybKNt7BKP+=qF=veBgc7VirZaXn4FUw@mail.gmail.com/
CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://lore.kernel.org/r/27105768dc19b395e7c8e7a80d056d1ff9c570d0.1635152553.git.linux@leemhuis.info
[jc: tweaked wording following Konstantin's recommendation]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Change all links from using the lkml redirector to the lore redirector,
as the kernel.org admin recently indicated: we shouldn't be using
lkml.kernel.org anymore because the domain can create confusion, as it
indicates it is only valid for messages sent to the LKML; the convention
has been to use https://lore.kernel.org/r/msgid for this reason.
In this process also change three links from using http to https.
Link: https://lore.kernel.org/r/20211006170025.qw3glxvocczfuhar@meerkat.local
CC: Thomas Gleixner <tglx@linutronix.de>
CC: Ingo Molnar <mingo@redhat.com>
CC: Borislav Petkov <bp@alien8.de>
CC: Hu Haowen <src.res@email.cn>
CC: Alex Shi <alexs@kernel.org>
CC: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Link: https://lore.kernel.org/r/5bb55bac6ba10fafab19bf2b21572dd0e2f8cea2.1633593385.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add a document to the subsystem/maintainer handbook section, which explains
what the tip tree is, how it operates and what rules and expectations it
has.
[ bp:
- Add a SPDX identifier, work in most comments from the thread.
- 9bf19b78a2 ("Documentation/submitting-patches: Document the SoB
chain") is also in the main Documentation but I'm leaving the
paragraph here because it has the proper structure - text talks about
SoBs and referencing somewhere else would interrupt the flow.
- Move backtraces in changelogs to main submitting-patches.rst.
- "Patch version information" is explained to a great detail in
submitting-patches.rst too.
- Hyperlink resend reminders section.
]
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Borislav Petkov <bp@suse.de>
Reviewed-by: Paul E. McKenney <paulmck@linux.ibm.com>
Link: https://lkml.kernel.org/r/20181107171149.165693799@linutronix.de
Link: https://lore.kernel.org/r/20210913153942.15251-3-bp@alien8.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
General rules for patch submission, coding style and related details are
available, but most subsystems have their subsystem-specific extra rules
which differ or go beyond the common rules.
Mark suggested to add a subsystem/maintainer handbook section, where
subsystem maintainers can explain their specific quirks.
Add the section and link to it from the submitting-patches document.
[ bp: Add a SPDX identifier. ]
Suggested-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Borislav Petkov <bp@suse.de>
Link: https://lkml.kernel.org/r/20181107171149.074948887@linutronix.de
Link: https://lore.kernel.org/r/20210913153942.15251-2-bp@alien8.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The documentation previously stated that LKML should be used as *last
resort*. However, scripts/get_maintainer.pl always suggests it and in a
discussion about changing that[0] it turned out that LKML should in fact
receive all patches.
Update documentation to make it clear that all patches should be sent to
LKML by default, in addition to any subsystem-specific lists.
[0]: https://lore.kernel.org/lkml/19a701a8d5837088aa7d8ba594c228c0e040e747.camel@perches.com/
Signed-off-by: Hannu Hartikainen <hannu@hrtk.in>
Link: https://lore.kernel.org/r/20210707133634.286840-1-hannu@hrtk.in
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
well contained to Documentation/ itself. Highlights include:
- The Chinese translators have been busy and show no signs of stopping
anytime soon. Italian has also caught up.
- Aditya Srivastava has been working on improvements to the kernel-doc
script.
- Thorsten continues his work on reporting-issues.rst and related
documentation around regression reporting.
- Lots of documentation updates, typo fixes, etc. as usual
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmCG5moPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5YCoUH/1q/O+IvS+JNkxneDxbB6OC799BQpabZHi7/
HbYfgfX0nKrV3NAwIhigsIj6WHRE+5p2rKiHOuQxL3daJyfZSqQl0/yI0Ag7Of4g
7y1FKBQrfqS6tJcyNckdtBfxYUQP9yCJY0xfIexkTNiujbmkMKDSJD7lKXd0AaTM
styCvTbgTPTzadL5bIHj/GxJ9s8DsxO3y9LGdRc+GrNzPFliMYWlJgbR28zjEKBm
UQzy7JGNBX3qTJwgjvv/myqRDy6MligvGrP+wG0KTnAHXKkvDFl3p46kPwzdk1JE
+F5sbboUWh20GLYy9t4MZOcq38FUcEPlRPXkxsGNyA8co5ij8+g=
=7db3
-----END PGP SIGNATURE-----
Merge tag 'docs-5.13' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"It's been a relatively busy cycle in docsland, though more than
usually well contained to Documentation/ itself. Highlights include:
- The Chinese translators have been busy and show no signs of
stopping anytime soon. Italian has also caught up.
- Aditya Srivastava has been working on improvements to the
kernel-doc script.
- Thorsten continues his work on reporting-issues.rst and related
documentation around regression reporting.
- Lots of documentation updates, typo fixes, etc. as usual"
* tag 'docs-5.13' of git://git.lwn.net/linux: (139 commits)
docs/zh_CN: add openrisc translation to zh_CN index
docs/zh_CN: add openrisc index.rst translation
docs/zh_CN: add openrisc todo.rst translation
docs/zh_CN: add openrisc openrisc_port.rst translation
docs/zh_CN: add core api translation to zh_CN index
docs/zh_CN: add core-api index.rst translation
docs/zh_CN: add core-api irq index.rst translation
docs/zh_CN: add core-api irq irqflags-tracing.rst translation
docs/zh_CN: add core-api irq irq-domain.rst translation
docs/zh_CN: add core-api irq irq-affinity.rst translation
docs/zh_CN: add core-api irq concepts.rst translation
docs: sphinx-pre-install: don't barf on beta Sphinx releases
scripts: kernel-doc: improve parsing for kernel-doc comments syntax
docs/zh_CN: two minor fixes in zh_CN/doc-guide/
Documentation: dev-tools: Add Testing Overview
docs/zh_CN: add translations in zh_CN/dev-tools/gcov
docs: reporting-issues: make people CC the regressions list
MAINTAINERS: add regressions mailing list
doc:it_IT: align Italian documentation
docs/zh_CN: sync reporting-issues.rst
...
Explain when a submitter should tag a patch or a patch series with the
"RESEND" tag.
This has been partially carved out from a tip subsystem handbook
patchset by Thomas Gleixner:
https://lkml.kernel.org/r/20181107171010.421878737@linutronix.de
and incorporates follow-on comments.
Signed-off-by: Borislav Petkov <bp@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add more blurb about the level of detail that should be contained in a
patch's commit message. Extend and make more explicit what text should
be added under the --- line. Extend examples and split into more easily
palatable paragraphs.
This has been partially carved out from a tip subsystem handbook
patchset by Thomas Gleixner:
https://lkml.kernel.org/r/20181107171010.421878737@linutronix.de
and incorporates follow-on comments.
Signed-off-by: Borislav Petkov <bp@suse.de>
Reviewed-by: Robert Richter <rrichter@amd.com>
Link: https://lore.kernel.org/r/20210215141949.GB21734@zn.tnic
[jc: Tweaked "example subjects" wording]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Document that backtraces in commit messages should be trimmed down to
the useful information only.
This has been carved out from a tip subsystem handbook patchset by
Thomas Gleixner:
https://lkml.kernel.org/r/20181107171010.421878737@linutronix.de
and incorporates follow-on comments.
Signed-off-by: Borislav Petkov <bp@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Clear-up any confusion surrounding the Fixes: tag with regards to the
need to Cc: the stable mailing list when submitting stable patch
candidates.
Signed-off-by: Lee Jones <lee.jones@linaro.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20210113163315.1331064-1-lee.jones@linaro.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Replace the lkml.org links with lore to better use a single source
that's more likely to stay available long-term.
Done by bash script:
cvt_lkml_to_lore ()
{
tmpfile=$(mktemp ./.cvt_links.XXXXXXX)
header=$(echo $1 | sed 's@/lkml/@/lkml/headers/@')
wget -qO - $header > $tmpfile
if [[ $? == 0 ]] ; then
link=$(grep -i '^Message-Id:' $tmpfile | head -1 | \
sed -r -e 's/^\s*Message-Id:\s*<\s*//' -e 's/\s*>\s*$//' -e 's@^@https://lore.kernel.org/r/@')
# echo "testlink: $link"
if [ -n "$link" ] ; then
wget -qO - $link > /dev/null
if [[ $? == 0 ]] ; then
echo $link
fi
fi
fi
rm -f $tmpfile
}
git grep -P -o "\bhttps?://(?:www.)?lkml.org/lkml[\/\w]+" $@ |
while read line ; do
echo $line
file=$(echo $line | cut -f1 -d':')
link=$(echo $line | cut -f2- -d':')
newlink=$(cvt_lkml_to_lore $link)
if [[ -n "$newlink" ]] ; then
sed -i -e "s#\b$link\b#$newlink#" $file
fi
done
Link: https://lore.kernel.org/patchwork/patch/1265849/#1462688
Signed-off-by: Joe Perches <joe@perches.com>
Link: https://lore.kernel.org/r/77cdb7f32cfb087955bfc3600b86c40bed5d4104.camel@perches.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, we do not have any documentation on commit reverts regarding
the requirement of Signed-off-by tag for it. This may be misleading to
the users.
Evaluating MISSING_SIGN_OFF checkpatch warnings on v4.13..v5.8 showed
that 4 out of 11 cases missing a sign-off are revert commits.
Add documentation regarding the same to document the community
consensus and let readers know.
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20201110174749.32068-1-yashsri421@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
From time to time, the novice kernel contributors do not add Reviewed-by
or Tested-by tags to the next versions of the patches. Mostly because
they are unaware that responsibility of adding these tags in next
version is on submitter, not maintainer.
Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
Link: https://lore.kernel.org/r/20201013162725.13572-1-krzk@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are two broken references at submitting-patches.rst:
Documentation/process/submitting-patches.rst:240: WARNING: undefined label: security-bugs (if the link has no caption the label must precede a section header)
Documentation/process/submitting-patches.rst:336: WARNING: undefined label: documentation/process/email-clients.rst (if the link has no caption the label must precede a section header)
Those are due to some recent renames and file moves.
It turns that maintaining :ref: is currently harder than using
:doc:, as we now have a script to help checking such references.
So, replace :ref: to :doc: there, making them to point to the
current file name.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/3ba405f579cf35ef2b39dd210d8ad46adc79f0ad.1599660067.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Git is fairly ubiquitous these days, and the additional information in
this documentation for preparing patches without it is not especially
relevant anymore and may serve to confuse new contributors.
The git request-pull comments were also removed, given that it is not a
tool well-suited to novice contributors, nor do maintainers especially
appreciate receiving unexpected request-pulls from new contributors.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Link: https://lore.kernel.org/r/20200903160545.83185-5-sir@cmpwn.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The repeated sign-offs necessary when a subsystem maintainer modifies an
incoming patch has been moved from submitting-patches.rst to
Documentation/maintainer, since the affairs of a subsystem maintainer
are not especially relevant to someone reading a guide for how to submit
their first patch.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Link: https://lore.kernel.org/r/20200903160545.83185-4-sir@cmpwn.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This adds a link to https://useplaintext.email to email-clients.rst,
which is a more exhaustive resource on configuring various mail clients
for plain text use. submitting-patches.rst is also updated to direct
readers to email-clients.rst to equip new contributors with the
requisite knowledge to become a good participant on the mailing lists.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20200903160545.83185-3-sir@cmpwn.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This follows similar changes throughout Documentation; these numbers
tend to get outdated and are not especially useful.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Link: https://lore.kernel.org/r/20200903160545.83185-2-sir@cmpwn.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The submitting patches mentions criteria for a fix to be called
"security fix". Add a link to document explaining the entire process
of handling security bugs.
Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Felipe Balbi <balbi@kernel.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20200827105319.9734-1-krzk@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
To make it a little clearer how to create a fixes tag,
add an example based on the preceeding gitconfig setup.
Signed-off-by: Tom Rix <trix@redhat.com>
Link: https://lore.kernel.org/r/20200710200115.21176-1-trix@redhat.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
If not .svg:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Acked-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Link: https://lore.kernel.org/r/20200621133630.46435-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
One of the recurring complaints from both maintainers and CI system
operators is that performing git-am on received patches is difficult
without knowing the parent object in the git history on which the
patches are based. Without this information, there is a high likelihood
that git-am will fail due to conflicts, which is particularly
frustrating to CI operators.
Git versions starting with v2.9.0 are able to automatically include
base-commit information using the --base flag of git-format-patch.
Document this usage in process/submitting-patches, and add the rationale
for its inclusion, plus instructions for those not using git on where
the "base-commit:" trailer should go.
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
http://linux.yyz.us/patch-format.html seems to be down since
approximately September 2018. There is a working archive copy on
arhive.org. Replaced the links in documenation + translations.
Signed-off-by: Jacob Huisman <jacobhuisman@kernelthusiast.com>
Reviewed-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <me@tobin.cc>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Jorge Ramirez-Ortiz <jorge.ramirez-ortiz@linaro.org>
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: Joe Perches <joe@perches.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Niklas Cassel <niklas.cassel@linaro.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The instructions for generating patches are given as shell commands
with variables as placeholders. They use the syntax "SRCTREE= linux",
which is wrong for the Bourne shell family (it runs the command
"linux" with the variable "SRCTREE" set to the empty string).
Remove the spaces to avoid confusion. This breaks the pretty alignment
but helps new contributors who try to run the commands as written.
Signed-off-by: Tom Levy <tomlevy93@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
...and use a commit with an obnoxiously long summary in the example to
make it abundantly clear that keeping the tag on a single line takes
priority over wrapping at 75 columns. Without the explicit exemption,
one might assume splitting the tag is acceptable, even encouraged, e.g.
due to being conditioned by checkpatch's line length warning.
Per Stephen's scripts[1] and implied by commit bf4daf12a9 ("checkpatch:
avoid some commit message long line warnings"), splitting the 'Fixes:'
tag across multiple lines is a no-no, presumably because parsing multi-
line tags is unnecessarily painful.
[1] https://lkml.kernel.org/r/20190216183433.71b7cfa7@canb.auug.org.au
Cc: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The accepted terminology will be Co-developed-by therefore lose the
capital letter from now on.
Link: http://lkml.kernel.org/r/1544808928-20002-2-git-send-email-jorge.ramirez-ortiz@linaro.org
Signed-off-by: Jorge Ramirez-Ortiz <jorge.ramirez-ortiz@linaro.org>
Acked-by: Himanshu Jha <himanshujha199640@gmail.com>
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: Joe Perches <joe@perches.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Niklas Cassel <niklas.cassel@linaro.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
In preparation to convert Documentation/network/netdev-FAQ.rst to
restructured text format. We would like to be able to reference 'the
canonical patch format' section.
Add rest label: 'the_canonical_patch_format'.
Signed-off-by: Tobin C. Harding <me@tobin.cc>
Signed-off-by: David S. Miller <davem@davemloft.net>
It seems that Linus looks for [GIT PULL] in subject lines to ensure that
pull requests don't get buried in the noise during merge windows. Update
the docs to reflect that.
[jc: From an impromptu post from willy, thus no SOB]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When Co-Developed-by tag was added, docs were only added to
Documention/process/5.Posting.rst and were not added to
Documention/process/submitting-patches.rst
Add documentation to Documention/process/submitting-patches.rst
Signed-off-by: Tobin C. Harding <me@tobin.cc>
[jc: tweaked commas in the subheading]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There shouldn't be a blank line at the beginning, if there is no
optional in-body "From" line. There must be a blank line between
the body of the explanation and the beginning of the S-o-b lines.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/process/submitting-patches.rst contains a non-ascii
character. Change it to the ascii equivalent.
Signed-off-by: Frank Rowand <frank.rowand@sony.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
