From: Bjorn Helgaas <bhelgaas@xxxxxxxxxx>
Add hints about how to write PCI patches and changelogs.
Signed-off-by: Bjorn Helgaas <bhelgaas@xxxxxxxxxx>
---
Documentation/PCI/00-INDEX | 2
Documentation/PCI/submitting-patches.txt | 153 ++++++++++++++++++++++++++++++
2 files changed, 155 insertions(+)
create mode 100644 Documentation/PCI/submitting-patches.txt
diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index 00c9a90b6f38..0f1d1de087f1 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -12,6 +12,8 @@ pci.txt
- info on the PCI subsystem for device driver authors
pcieaer-howto.txt
- the PCI Express Advanced Error Reporting Driver Guide HOWTO
+submitting-patches.txt
+ - hints about how to submit PCI patches
endpoint/pci-endpoint.txt
- guide to add endpoint controller driver and endpoint function driver.
endpoint/pci-endpoint-cfs.txt
diff --git a/Documentation/PCI/submitting-patches.txt b/Documentation/PCI/submitting-patches.txt
new file mode 100644
index 000000000000..d6a694182446
--- /dev/null
+++ b/Documentation/PCI/submitting-patches.txt
@@ -0,0 +1,153 @@
+Start with Documentation/process/submitting-patches.rst for general
+guidance.
+
+These are things I look at when reviewing patches. Most of the technical
+things are obvious or covered elsewhere. Some things here are cosmetic
+personal preferences, but consistency makes maintenance easier. I silently
+fix up most of the trivial things, so don't get too hung up on the details.
+
+Write the patch:
+
+ - Make each patch small but complete by itself. Don't worry about making
+ patches *too* small; it's trivial for me to squash patches together if
+ necessary.
+
+ - Make sure the kernel builds after every patch. You can't introduce a
+ problem in one patch and fix it in a subsequent patch. If one of the
+ autobuilders finds a build issue, I'll revert the patch unless you send
+ a fix.
+
+ - Please do send whitespace and coding style fixes, but don't mix them
+ with other substantive changes. It's easier for people to backport
+ fixes if whitespace changes are at the end of a series.
+
+ - Wrap code and comments to fit in 80 columns. Exception: I prefer
+ printk strings to be in one piece for searchability, so don't split
+ quoted strings to make them fit in 80 columns.
+
+ - Follow the existing style for code, names, and indentation. When
+ you're finished, the file should look like it was all written by one
+ person.
+
+Write the changelog title (first line of the changelog):
+
+ - Follow the existing convention Run "git log --oneline <file>" and make
+ your subject line match previous changes in format, capitalization, and
+ sentence structure. For example, native host bridge driver patch
+ titles look like this:
+
+ PCI: vmd: Remove IRQ affinity so we can allocate more IRQs
+ PCI: mediatek: Add MSI support for MT2712 and MT7622
+ PCI: rockchip: Remove IRQ domain if probe fails
+
+ - Write a complete sentence, starting with a capitalized verb.
+
+ - Include specific details, e.g., write "Add XYZ controller support"
+ instead of "add support for new generation controller".
+
+ - Do not include a trailing period in the title.
+
+Write the changelog:
+
+ - Make the changelog readable without the title. The changelog is not a
+ continuation of the title, so it should make sense by itself. Always
+ include a changelog, even if it is the same as the title.
+
+ - Explain the change (not just "Fix a problem"), but do it as concisely
+ as possible. Include function names, references to sections of the
+ spec, URLs for bug reports, etc. This makes reviewing and future
+ maintenance easier.
+
+ - Capitalize initialisms ("PCI", "IRQ", "ID", "MSI", etc) in all English
+ text, including title, changelog, and comments. These are usually
+ written in lower-case in the C code, but please follow normal English
+ conventions in text.
+
+ - Include "()" after function names and "[]" after array names as a
+ visual clue that these refer to something in the code.
+
+ - Include dmesg output and stack trace when relevant. Prune details that
+ aren't relevant, e.g., you can usually remove timestamps and function
+ addresses. The objective is to concisely illustrate the issue and make
+ it discoverable by search engines.
+
+ - Use spaces (not tabs) in the changelog because "git log" indents the
+ changelog and things aligned with tabs won't stay aligned.
+
+ - Wrap changelogs to fit in 80 columns when shown by "git show", which
+ adds 4 spaces. I use "textwidth=75" in vim.
+
+ - Order tags as suggested by Ingo [1] (extended):
+
+ Fixes:
+ Link:
+ Reported-by:
+ Tested-by:
+ Signed-off-by: (author)
+ Signed-off-by: (chain)
+ Reviewed-by:
+ Acked-by:
+ Cc: stable@xxxxxxxxxxxxxxx # 3.4+
+ Cc: (other)
+
+ - Include a "Fixes:" reference when you're fixing a previous commit and
+ copy the author of the previous commit. This helps people figure out
+ where a change needs to be backported.
+
+ - Include specific commit references when possible, e.g., 'e77f847df54c
+ ("PCI: rockchip: Add Rockchip PCIe controller support")'. I use this
+ alias to generate them:
+
+ alias gsr='git --no-pager show -s --abbrev-commit --abbrev=12 --pretty=format:"%h (\"%s\")%n"'
+
+ - Include bugzilla URLs if available (kernel.org bugzilla preferred),
+ e.g.,
+
+ Link: https://bugzilla.redhat.com/show_bug.cgi?id=1409201
+
+ - Include problem report URLs. Use kernel.org URLs, e.g.,
+ http://lkml.kernel.org/r/<Message-ID>, because they don't depend on
+ other mirror sites:
+
+ Link: http://lkml.kernel.org/r/4bcbcbc1-7c79-09f0-5071-bc2f53bf6574@xxxxxxxxx
+
+ - Include specific references to the spec when possible, e.g., "PCIe
+ r3.1, sec 7.8.2". If you're talking about something mentioned in the
+ spec, use the same name and capitalization as the spec.
+
+ - Include a "Cc: stable@xxxxxxxxxxxxxxx" tag if you want one, and
+ indicate which kernels need it.
+
+Post the patch:
+
+ - Use scripts/get_maintainer.pl to find the maintainers of files you're
+ changing, and copy the maintainers and authors of recent or related
+ changes.
+
+ - Always copy linux-pci@xxxxxxxxxxxxxxx and linux-kernel@xxxxxxxxxxxxxxx.
+ I don't apply patches that haven't appeared on the linux-pci mailing
+ list, even if you send them to me directly. This is partly to make
+ sure everyone has a chance to review it and partly because I use the
+ Patchwork tracker [2], which only tracks things on the linux-pci list.
+
+ - If you send more than one patch and they're related, always include a
+ "[0/n]" cover letter. This makes it easy for me to reply to the cover
+ letter saying "I applied this series." I use "stg -e -v v1 --to=...
+ patch1..patchN".
+
+ - If you post a new version, please make sure it includes "[v2]" or
+ similar in the subject line. If it's a series, I want a new version
+ of the entire series. I don't want updates of individual patches
+ within the series -- that's too hard for me to keep track of. It's
+ perfectly fine if some patches in a v2 series are the same as in the
+ initial posting.
+
+ - If you want the patch in the current release, include a cover letter
+ and tell me that. Otherwise, I assume all patches are intended for the
+ next merge window.
+
+ - If you're really gung-ho, you can go to Patchwork [2] and mark your
+ superseded patches as "Superseded" so I don't have to do that myself.
+
+[1] http://lkml.kernel.org/r/20120711080446.GA17713@xxxxxxxxx
+[2] https://patchwork.ozlabs.org/project/linux-pci/list/
