summaryrefslogtreecommitdiff
path: root/Documentation/process/submitting-patches.rst
AgeCommit message (Collapse)AuthorFilesLines
2023-11-27docs: submitting-patches: improve the base commit explanationBorislav Petkov (AMD)1-4/+11
After receiving a second patchset this week without knowing which tree it applies on and trying to apply it on the obvious ones and failing, make sure the base tree information which needs to be supplied in the 0th message of the patchset is spelled out more explicitly. Also, make the formulations stronger as this really is a requirement and not only a useful thing anymore. Signed-off-by: "Borislav Petkov (AMD)" <bp@alien8.de> change-id: <unique-series-id> base-commit: <commit-id-or-tag> Reviewed-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231115170330.16626-1-bp@alien8.de
2023-10-10docs: submitting-patches: encourage direct notifications to commentersThomas Weißschuh1-0/+2
Commenters may not receive new versions of patches via the lists. Without a directed notification to them they might miss those new versions. This is frustrating for the patch developers as they don't receive their earned Reviewed-by. It is also frustrating for the commenters, as they might think their review got ignored or they have to dig up new versions from the archive manually. So encourage patch submitters to make sure that all commenters get notified also when no Reviewed-by was issued yet. Signed-off-by: Thomas Weißschuh <linux@weissschuh.net> Reviewed-by: Christoph Hellwig <hch@lst.de> Acked-by: Alexander Dahl <ada@thorsis.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231003-docs-cc-reviewer-v2-1-f93fb946e21e@weissschuh.net
2023-10-10docs: submitting-patches: Suggest a longer expected time for responsesMark Brown1-4/+4
While some subsystems do typically have very fast turnaround times on review this is far from standard over the kernel and is likely to set unrealistic expectations for submitters. Tell submitters to expect 2-3 weeks instead, this will cover more of the kernel. Signed-off-by: Mark Brown <broonie@kernel.org> Reviewed-by: Javier Martinez Canillas <javierm@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20230913-submitting-patches-delay-v1-1-a2d48c5ca205@kernel.org
2023-05-19docs: submitting-patches: Discuss interleaved repliesKees Cook1-0/+25
Top-posting has been strongly discouraged in Linux development, but this was actually not written anywhere in the common documentation about sending patches and replying to reviews. Add a section about trimming and interleaved replies. Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Kees Cook <keescook@chromium.org> Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20230511184131.gonna.399-kees@kernel.org
2023-04-28Merge tag 'mm-nonmm-stable-2023-04-27-16-01' of ↵Linus Torvalds1-8/+18
git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm Pull non-MM updates from Andrew Morton: "Mainly singleton patches all over the place. Series of note are: - updates to scripts/gdb from Glenn Washburn - kexec cleanups from Bjorn Helgaas" * tag 'mm-nonmm-stable-2023-04-27-16-01' of git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm: (50 commits) mailmap: add entries for Paul Mackerras libgcc: add forward declarations for generic library routines mailmap: add entry for Oleksandr ocfs2: reduce ioctl stack usage fs/proc: add Kthread flag to /proc/$pid/status ia64: fix an addr to taddr in huge_pte_offset() checkpatch: introduce proper bindings license check epoll: rename global epmutex scripts/gdb: add GDB convenience functions $lx_dentry_name() and $lx_i_dentry() scripts/gdb: create linux/vfs.py for VFS related GDB helpers uapi/linux/const.h: prefer ISO-friendly __typeof__ delayacct: track delays from IRQ/SOFTIRQ scripts/gdb: timerlist: convert int chunks to str scripts/gdb: print interrupts scripts/gdb: raise error with reduced debugging information scripts/gdb: add a Radix Tree Parser lib/rbtree: use '+' instead of '|' for setting color. proc/stat: remove arch_idle_time() checkpatch: check for misuse of the link tags checkpatch: allow Closes tags with links ...
2023-04-24Merge tag 'docs-6.4' of git://git.lwn.net/linuxLinus Torvalds1-11/+8
Pull documentation updates from Jonathan Corbet: "Commit volume in documentation is relatively low this time, but there is still a fair amount going on, including: - Reorganize the architecture-specific documentation under Documentation/arch This makes the structure match the source directory and helps to clean up the mess that is the top-level Documentation directory a bit. This work creates the new directory and moves x86 and most of the less-active architectures there. The current plan is to move the rest of the architectures in 6.5, with the patches going through the appropriate subsystem trees. - Some more Spanish translations and maintenance of the Italian translation - A new "Kernel contribution maturity model" document from Ted - A new tutorial on quickly building a trimmed kernel from Thorsten Plus the usual set of updates and fixes" * tag 'docs-6.4' of git://git.lwn.net/linux: (47 commits) media: Adjust column width for pdfdocs media: Fix building pdfdocs docs: clk: add documentation to log which clocks have been disabled docs: trace: Fix typo in ftrace.rst Documentation/process: always CC responsible lists docs: kmemleak: adjust to config renaming ELF: document some de-facto PT_* ABI quirks Documentation: arm: remove stih415/stih416 related entries docs: turn off "smart quotes" in the HTML build Documentation: firmware: Clarify firmware path usage docs/mm: Physical Memory: Fix grammar Documentation: Add document for false sharing dma-api-howto: typo fix docs: move m68k architecture documentation under Documentation/arch/ docs: move parisc documentation under Documentation/arch/ docs: move ia64 architecture docs under Documentation/arch/ docs: Move arc architecture docs under Documentation/arch/ docs: move nios2 documentation under Documentation/arch/ docs: move openrisc documentation under Documentation/arch/ docs: move superh documentation under Documentation/arch/ ...
2023-04-21Documentation/process: always CC responsible listsKrzysztof Kozlowski1-11/+8
The "Select the recipients for your patch" part about CC-ing mailing lists is a bit vague and might be understood that only some lists should be Cc-ed. That's not what most of the maintainers expect. For given code, associated mailing list must always be CC-ed, because the list is used for reviewing and testing patches. Example are the Devicetree bindings patches, which are tested iff Devicetree mailing list is CC-ed. Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> Link: https://lore.kernel.org/r/20230413165501.47442-1-krzysztof.kozlowski@linaro.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-04-19docs: process: allow Closes tags with linksMatthieu Baerts1-8/+18
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/20230315181205.f3av7h6owqzzw64p@meerkat.local/ 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/20230315181205.f3av7h6owqzzw64p@meerkat.local/ [3] Link: https://lore.kernel.org/all/CAHk-=wgs38ZrfPvy=nOwVkVzjpM3VFU1zobP37Fwd_h9iAD5JQ@mail.gmail.com/ [4] Link: https://lore.kernel.org/all/688cd6cb-90ab-6834-a6f5-97080e39ca8e@leemhuis.info/ [5] Link: https://lore.kernel.org/linux-doc/2194d19d-f195-1a1e-41fc-7827ae569351@leemhuis.info/ [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 <matthieu.baerts@tessares.net> Suggested-by: Thorsten Leemhuis <linux@leemhuis.info> Acked-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Acked-by: Joe Perches <joe@perches.com> Cc: Andy Whitcroft <apw@canonical.com> Cc: Bagas Sanjaya <bagasdotme@gmail.com> Cc: Daniel Vetter <daniel@ffwll.ch> Cc: David Airlie <airlied@gmail.com> Cc: Dwaipayan Ray <dwaipayanray1@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Kai Wasserbäch <kai@dev.carbon-project.org> Cc: Linus Torvalds <torvalds@linux-foundation.org> Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
2023-04-02Merge tag 'driver-core-6.3-rc5' of ↵Linus Torvalds1-1/+1
git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core Pull driver core fixes from Greg KH: "Here are three small changes for 6.3-rc5 semi-related to driver core stuff: - documentation update where we move the security_bugs file to a more relevant location. - mdt/spi-nor debugfs memory leak fix that's been floating around for a long time and acked by the maintainer - cacheinfo bugfix for a regression in 6.3-rc1 All have been in linux-next with no reported problems" * tag 'driver-core-6.3-rc5' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core: cacheinfo: Fix LLC is not exported through sysfs Documentation/security-bugs: move from admin-guide/ to process/ mtd: spi-nor: fix memory leak when using debugfs_lookup()
2023-03-14docs: process: typo fixXujun Leng1-1/+1
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>
2023-03-12Documentation/security-bugs: move from admin-guide/ to process/Vegard Nossum1-1/+1
Jiri Kosina, Jonathan Corbet, and Willy Tarreau all expressed a desire to move this document under process/. Create a new section for security issues in the index and group it with embargoed-hardware-issues. I'm doing this at the start of the series to make all the subsequent changes show up in 'git blame'. Existing references were updated using: git grep -l security-bugs ':!Documentation/translations/' | xargs sed -i 's|admin-guide/security-bugs|process/security-bugs|g' git grep -l security-bugs Documentation/translations/ | xargs sed -i 's|Documentation/admin-guide/security-bugs|Documentation/process/security-bugs|g' git grep -l security-bugs Documentation/translations/ | xargs sed -i '/Original:/s|\.\./admin-guide/security-bugs|\.\./process/security-bugs|g' Notably, the page is not moved in the translations (due to my lack of knowledge of these languages), but the translations have been updated to point to the new location of the original document where these references exist. Link: https://lore.kernel.org/all/nycvar.YFH.7.76.2206062326230.10851@cbobk.fhfr.pm/ Suggested-by: Jiri Kosina <jikos@kernel.org> Cc: Alex Shi <alexs@kernel.org> Cc: Yanteng Si <siyanteng@loongson.cn> Cc: Hu Haowen <src.res@email.cn> Cc: Federico Vaga <federico.vaga@vaga.pv.it> Cc: Tsugikazu Shibata <tshibata@ab.jp.nec.com> Cc: Minchan Kim <minchan@kernel.org> Cc: Jeimi Lee <jamee.lee@samsung.com> Cc: Carlos Bilbao <carlos.bilbao@amd.com> Cc: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Acked-by: Carlos Bilbao <carlos.bilbao@amd.com> Reviewed-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Acked-by: Federico Vaga <federico.vaga@vaga.pv.it> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Link: https://lore.kernel.org/r/20230305220010.20895-2-vegard.nossum@oracle.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2023-03-01Merge tag 'docs-6.3-2' of git://git.lwn.net/linuxLinus Torvalds1-4/+5
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
2023-02-26Documentation: simplify and clarify DCO contribution example languageLinus Torvalds1-1/+1
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: af45f32d25cc ("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>
2023-02-23docs: recommend using Link: whenever using Reported-by:Thorsten Leemhuis1-4/+5
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>
2022-09-27Documentation: process/submitting-patches: misspelling "mesages"Rong Tao1-2/+2
Fix spelling mistakes, "mesages" should be spelled "messages". Signed-off-by: Rong Tao <rtoax@foxmail.com> Link: https://lore.kernel.org/r/tencent_924BF0B25425E2D5673409D1CF604F682505@qq.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-07-15docs: process: remove outdated submitting-drivers.rstLukas Bulwahn1-3/+2
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 <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>
2022-05-10Documentation/process: use scripts/get_maintainer.pl on patchesKrzysztof Kozlowski1-3/+4
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>
2022-04-28docs: submitting-patches: Fix crossref to 'The canonical patch format'Akira Yokosawa1-1/+1
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]: 2ae19acaa50a ("Documentation: Add "how to write a good patch summary" to SubmittingPatches") Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Fixes: 5903019b2a5e ("Documentation/SubmittingPatches: convert it to ReST markup") Fixes: 9b2c76777acc ("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>
2022-04-05Documentation/process: mention patch changelog in review processKrzysztof Kozlowski1-1/+4
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>
2022-01-27docs: process: submitting-patches: Clarify the Reported-by usageAndy Shevchenko1-1/+2
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>
2021-12-17Remove mentions of the Trivial Patch MonkeyMiguel Ojeda1-19/+0
Apparently, it was decided that trivial@kernel.org is no longer used. Link: https://lore.kernel.org/lkml/fe86efbd-4e03-76c8-55cf-dabd33e85823@infradead.org/ Co-developed-by: Joe Perches <joe@perches.com> Signed-off-by: Joe Perches <joe@perches.com> Signed-off-by: Miguel Ojeda <ojeda@kernel.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20211214191415.GA19070@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-11-30Documentation/process: fix self referenceErik Ekman1-1/+2
Instead link to the device tree document with the same name. Signed-off-by: Erik Ekman <erik@kryo.se> Link: https://lore.kernel.org/r/20211119200758.642474-1-erik@kryo.se Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-11-17Documentation/process: fix a cross referenceMauro Carvalho Chehab1-2/+2
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: 604370e106cc ("Documentation/process: Add maintainer handbooks section") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-10-28docs: submitting-patches: make section about the Link: tag more explicitThorsten Leemhuis1-11/+22
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>
2021-10-12docs: use the lore redirector everywhereThorsten Leemhuis1-2/+2
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>
2021-09-14Documentation/process: Add tip tree handbookThomas Gleixner1-0/+3
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. - 9bf19b78a203 ("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>
2021-09-14Documentation/process: Add maintainer handbooks sectionThomas Gleixner1-0/+4
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>
2021-07-25docs: submitting-patches: clarify the role of LKMLHannu Hartikainen1-5/+5
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>
2021-06-17docs: process: submitting-patches.rst: avoid using ReST :doc:`foo` markupMauro Carvalho Chehab1-17/+15
The :doc:`foo` tag is auto-generated via automarkup.py. So, use the filename at the sources, instead of :doc:`foo`. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/d172ab629c3e32c8d27ed4b9d2a209933e2a7178.1623824363.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-04-26Merge tag 'docs-5.13' of git://git.lwn.net/linuxLinus Torvalds1-34/+67
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 ...
2021-04-14Documentation/submitting-patches: Document RESEND tag on patchesBorislav Petkov1-0/+10
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>
2021-03-07Documentation/submitting-patches: Extend commit message layout descriptionBorislav Petkov1-34/+57
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>
2021-03-03docs: networking: drop special stable handlingJakub Kicinski1-5/+0
Leave it to Greg. Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
2021-02-05Documentation/submitting-patches: Add blurb about backtraces in commit messagesBorislav Petkov1-0/+20
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>
2021-01-18docs: submitting-patches: Emphasise the requirement to Cc: stable when using ↵Lee Jones1-0/+5
Fixes: tag 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>
2021-01-11Documentation: Replace lkml.org links with loreJoe Perches1-2/+2
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>
2020-12-21Documentation/submitting-patches: Document the SoB chainBorislav Petkov1-0/+6
Document what a chain of Signed-off-by's in a patch commit message should mean, explicitly. 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> Link: https://lore.kernel.org/r/20201217183756.GE23634@zn.tnic Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-21docs: submitting-patches: Trivial - fix grammatical errorLee Jones1-1/+1
"it is a used" does not make sense. Should be "it is used". Signed-off-by: Lee Jones <lee.jones@linaro.org> Link: https://lore.kernel.org/r/20201216134654.271508-1-lee.jones@linaro.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-11-14Documentation: include sign off for revertsAditya Srivastava1-0/+2
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>
2020-10-22docs: submitting-patches: describe preserving review/test tagsKrzysztof Kozlowski1-0/+7
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>
2020-09-10docs: submitting-patches: use :doc: for referencesMauro Carvalho Chehab1-12/+8
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>
2020-09-04submitting-patches.rst: presume git will be usedDrew DeVault1-132/+16
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>
2020-09-04Documentation/maintainer: rehome sign-off processDrew DeVault1-46/+0
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>
2020-09-04Documentation/process: expand plain-text adviceDrew DeVault1-0/+3
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>
2020-09-04submitting-patches.rst: remove heading numberingDrew DeVault1-34/+34
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>
2020-09-01docs: process: Add cross-link to security-bugsKrzysztof Kozlowski1-1/+2
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>
2020-07-23docs: process: Add an example for creating a fixes tagTom Rix1-0/+5
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>
2020-06-26Replace HTTP links with HTTPS ones: Documentation/processAlexander A. Klimov1-2/+2
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>
2020-05-05docs: dt: convert submitting-patches.txt to ReST formatMauro Carvalho Chehab1-1/+1
- 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>
2019-11-07docs: process: Add base-commit trailer usageKonstantin Ryabitsev1-1/+52
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>
generated by cgit v1.2.3 (git 2.39.0) at 2024-07-28 11:15:41 +0300