Hi Jon,
This series is against 6.0-rc1, so it should apply fine on the top of your tree.
After applying one fix sent to ACPI:
https://lore.kernel.org/linux-acpi/[email protected]/T/#u
make htmldocs (with Sphinx 2.4.4) produces a very clean result:
:
Warning: Documentation/devicetree/bindings/regulator/siliconmitus,sm5703
-regulator.yaml references a file that doesn't exist: Documentation/devicetree/b
indings/mfd/siliconmitus,sm5703.yaml
SPHINX htmldocs --> file:///new_devel/v4l/docs/Documentation/output
PARSE include/uapi/linux/dvb/ca.h
PARSE include/uapi/linux/dvb/dmx.h
PARSE include/uapi/linux/dvb/frontend.h
PARSE include/uapi/linux/dvb/net.h
PARSE include/uapi/linux/videodev2.h
PARSE include/uapi/linux/media.h
PARSE include/uapi/linux/cec.h
PARSE include/uapi/linux/lirc.h
Using sphinx_rtd_theme theme
The only warning is due to a driver that got its upstream way for MFD, but it seems that
the corresponding regulator driver has lost its way.
If we can fix such warning, we could add a sort of "Werror" for:
- some ABI issues;
- kernel-doc warnings/errors;
- broken kernel-doc warnings.
Although there will still have Sphinx warnings that can come up from various sources,
this could help to keep documentation on a better shape, as time goes by.
Regards,
Mauro
Mauro Carvalho Chehab (13):
scripts: kernel-doc: add support for EXPORT_SYMBOL variants
docs: update vmemmap_dedup.rst reference
docs: ja_JP: remove SubmittingPatches
docs: zh_CN: remove references to rust documentation
dt-bindings: arm: update arm,coresight-cpu-debug.yaml reference
Documentation: coresight: fix a documentation build warning
MAINTAINERS: fix wildcard for mfd da90* files
MAINTAINERS: fix a typo for hpe,gxp-spifi.yaml
ABI: sysfs-bus-nvdimm: fix a doc build warning
docs: leds: add leds-qcom-lpg.rst to the index file
fscache: fix kernel-doc markup on two functions
serial: document start_rx member at struct uart_ops
fs/dcache: fix a kernel-doc markup
Documentation/ABI/testing/sysfs-bus-nvdimm | 2 +
Documentation/leds/index.rst | 1 +
.../trace/coresight/coresight-cpu-debug.rst | 2 +-
Documentation/trace/coresight/coresight.rst | 2 +-
.../translations/ja_JP/SubmittingPatches | 722 ------------------
.../zh_CN/doc-guide/kernel-doc.rst | 2 -
MAINTAINERS | 4 +-
drivers/gpu/drm/scheduler/sched_main.c | 1 +
include/drm/gpu_scheduler.h | 1 +
include/linux/dcache.h | 10 +-
include/linux/fscache.h | 4 +-
include/linux/serial_core.h | 8 +
mm/hugetlb_vmemmap.h | 2 +-
scripts/kernel-doc | 8 +-
14 files changed, 33 insertions(+), 736 deletions(-)
delete mode 100644 Documentation/translations/ja_JP/SubmittingPatches
--
2.37.1
There is a note on this file that, using a robot to translate,
says:
"The kernel-doc cannot contain Rust code: please refer
to Documentation/rust/general-information.rst."
Such note doesn't exist at the original file anymore, so, just remove
it from the translation, in order to solve this warning:
Warning: Documentation/translations/zh_CN/doc-guide/kernel-doc.rst references a file that doesn't exist: Documentation/rust/general-information.rst
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 2 --
1 file changed, 2 deletions(-)
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index ccfb9b8329c2..9fd170faf951 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -14,8 +14,6 @@ Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用
实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循
此处描述的风格。
-.. note:: kernel-doc无法包含Rust代码：请参考 Documentation/rust/general-information.rst 。
-
从注释中提取kernel-doc结构，并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的
类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。
--
2.37.1
Changeset 66d052047ca8 ("dt-bindings: arm: Convert CoreSight CPU debug to DT schema")
renamed: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
to: Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml.
Update its cross-reference accordingly.
Fixes: 66d052047ca8 ("dt-bindings: arm: Convert CoreSight CPU debug to DT schema")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
Documentation/trace/coresight/coresight-cpu-debug.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/trace/coresight/coresight-cpu-debug.rst b/Documentation/trace/coresight/coresight-cpu-debug.rst
index 993dd294b81b..79bbe587e5e8 100644
--- a/Documentation/trace/coresight/coresight-cpu-debug.rst
+++ b/Documentation/trace/coresight/coresight-cpu-debug.rst
@@ -117,7 +117,7 @@ divide into below cases:
Device Tree Bindings
--------------------
-See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details.
+See Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml for details.
How to use the module
--
2.37.1
Using wildcards for cross-reference doesn't work, as the Sphinx
automarkup plugin is not smart enough. So, changeset
c06475910b52 ("Documentation: coresight: Escape coresight bindings file wildcard")
tried to fix it, but at the wrong way, as it the building system
will keep producing warnings about that:
Warning: Documentation/trace/coresight/coresight.rst references a file that doesn't exist: Documentation/devicetree/bindings/arm/arm,coresight-
As automarkup will still try (and fail) to create a cross reference.
So, instead, change the markup to ensure that the warning won't be
reported.
Fixes: c06475910b52 ("Documentation: coresight: Escape coresight bindings file wildcard")
Cc: Bagas Sanjaya <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
Documentation/trace/coresight/coresight.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
index 4a71ea6cb390..826e59a698da 100644
--- a/Documentation/trace/coresight/coresight.rst
+++ b/Documentation/trace/coresight/coresight.rst
@@ -130,7 +130,7 @@ Misc:
Device Tree Bindings
--------------------
-See Documentation/devicetree/bindings/arm/arm,coresight-\*.yaml for details.
+See ``Documentation/devicetree/bindings/arm/arm,coresight-*.yaml`` for details.
As of this writing drivers for ITM, STMs and CTIs are not provided but are
expected to be added as the solution matures.
--
2.37.1
There are now several new EXPORT_SYMBOL variants. Add support for
them.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
scripts/kernel-doc | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index aea04365bc69..94a062ef1835 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -255,7 +255,7 @@ my $doc_inline_start = '^\s*/\*\*\s*$';
my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
my $doc_inline_end = '^\s*\*/\s*$';
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
-my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
+my $export_symbol = '^\s*(EXPORT_SYMBOL|EXPORT_SYMBOL_GPL|EXPORT_SYMBOL_NS|EXPORT_SYMBOL_NS_GPL|EXPORT_SYMBOL_ACPI_LIB|EXPORT_INDIRECT_CALLABLE)\s*\(\s*(\w+)[,\w\s]*\)\s*;';
my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
@@ -2419,12 +2419,12 @@ found on PATH.
=item -export
Only output documentation for the symbols that have been exported using
-EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+EXPORT_SYMBOL() and variants in any input FILE or -export-file FILE.
=item -internal
Only output documentation for the symbols that have NOT been exported using
-EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+EXPORT_SYMBOL() nor variants in any input FILE or -export-file FILE.
=item -function NAME
@@ -2452,7 +2452,7 @@ Do not output DOC: sections.
=item -export-file FILE
Specify an additional FILE in which to look for EXPORT_SYMBOL() and
-EXPORT_SYMBOL_GPL().
+variants.
To be used with -export or -internal.
--
2.37.1
Fix this doc build warning:
./include/linux/serial_core.h:397: warning: Function parameter or member 'start_rx' not described in 'uart_ops'
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
include/linux/serial_core.h | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/include/linux/serial_core.h b/include/linux/serial_core.h
index aef3145f2032..6e4f4765d209 100644
--- a/include/linux/serial_core.h
+++ b/include/linux/serial_core.h
@@ -141,6 +141,14 @@ struct gpio_desc;
* Locking: none.
* Interrupts: caller dependent.
*
+ * @start_rx: ``void ()(struct uart_port *port)``
+ *
+ * Start receiving characters.
+ *
+ * Locking: @port->lock taken.
+ * Interrupts: locally disabled.
+ * This call must not sleep
+ *
* @stop_rx: ``void ()(struct uart_port *port)``
*
* Stop receiving characters; the @port is in the process of being closed.
--
2.37.1
Address this warning:
Documentation/leds/leds-qcom-lpg.rst: WARNING: o documento não está incluído em nenhum toctree
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
Documentation/leds/index.rst | 1 +
drivers/gpu/drm/scheduler/sched_main.c | 1 +
include/drm/gpu_scheduler.h | 1 +
3 files changed, 3 insertions(+)
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
index e5d63b940045..014e009b0761 100644
--- a/Documentation/leds/index.rst
+++ b/Documentation/leds/index.rst
@@ -25,4 +25,5 @@ LEDs
leds-lp5562
leds-lp55xx
leds-mlxcpld
+ leds-qcom-lpg
leds-sc27xx
diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
index 68317d3a7a27..56c53a616816 100644
--- a/drivers/gpu/drm/scheduler/sched_main.c
+++ b/drivers/gpu/drm/scheduler/sched_main.c
@@ -994,6 +994,7 @@ static int drm_sched_main(void *param)
* used
* @score: optional score atomic shared with other schedulers
* @name: name used for debugging
+ * @dev: Device structure
*
* Return 0 on success, otherwise error code.
*/
diff --git a/include/drm/gpu_scheduler.h b/include/drm/gpu_scheduler.h
index addb135eeea6..f31988e03256 100644
--- a/include/drm/gpu_scheduler.h
+++ b/include/drm/gpu_scheduler.h
@@ -435,6 +435,7 @@ struct drm_sched_backend_ops {
* @_score: score used when the driver doesn't provide one
* @ready: marks if the underlying HW is ready to work
* @free_guilty: A hit to time out handler to free the guilty job.
+ * @dev: Device structure
*
* One scheduler is implemented for each hardware ring.
*/
--
2.37.1
The obj parameter was replaced by a cookie. Update docs
accordingly.
It solves those doc build warnings:
./include/linux/fscache.h:270: warning: Function parameter or member 'cookie' not described in 'fscache_use_cookie'
./include/linux/fscache.h:270: warning: Excess function parameter 'object' description in 'fscache_use_cookie'
./include/linux/fscache.h:287: warning: Function parameter or member 'cookie' not described in 'fscache_unuse_cookie'
./include/linux/fscache.h:287: warning: Excess function parameter 'object' description in 'fscache_unuse_cookie'
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
include/linux/fscache.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/include/linux/fscache.h b/include/linux/fscache.h
index 720874e6ee94..bc089ce2c903 100644
--- a/include/linux/fscache.h
+++ b/include/linux/fscache.h
@@ -258,7 +258,7 @@ struct fscache_cookie *fscache_acquire_cookie(struct fscache_volume *volume,
/**
* fscache_use_cookie - Request usage of cookie attached to an object
- * @object: Object description
+ * @cookie: The cookie to be attached
* @will_modify: If cache is expected to be modified locally
*
* Request usage of the cookie attached to an object. The caller should tell
@@ -274,7 +274,7 @@ static inline void fscache_use_cookie(struct fscache_cookie *cookie,
/**
* fscache_unuse_cookie - Cease usage of cookie attached to an object
- * @object: Object description
+ * @cookie: The cookie to be unused
* @aux_data: Updated auxiliary data (or NULL)
* @object_size: Revised size of the object (or NULL)
*
--
2.37.1
The entry has hpe,gxp-spi.yaml instead, causing this warning:
Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/spi/hpe,gxp-spi.yaml
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
MAINTAINERS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index ae1a12b3f090..c27a875f52b0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2178,7 +2178,7 @@ M: Jean-Marie Verdun <[email protected]>
M: Nick Hawkins <[email protected]>
S: Maintained
F: Documentation/devicetree/bindings/arm/hpe,gxp.yaml
-F: Documentation/devicetree/bindings/spi/hpe,gxp-spi.yaml
+F: Documentation/devicetree/bindings/spi/hpe,gxp-spifi.yaml
F: Documentation/devicetree/bindings/timer/hpe,gxp-timer.yaml
F: arch/arm/boot/dts/hpe-bmc*
F: arch/arm/boot/dts/hpe-gxp*
--
2.37.1
Fix this warning:
Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/mfd/da90*.yaml
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
MAINTAINERS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index 8a5012ba6ff9..ae1a12b3f090 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6011,7 +6011,7 @@ W: http://www.dialog-semiconductor.com/products
F: Documentation/devicetree/bindings/input/da90??-onkey.txt
F: Documentation/devicetree/bindings/input/dlg,da72??.txt
F: Documentation/devicetree/bindings/mfd/da90*.txt
-F: Documentation/devicetree/bindings/mfd/da90*.yaml
+F: Documentation/devicetree/bindings/mfd/dlg,da90*.yaml
F: Documentation/devicetree/bindings/regulator/dlg,da9*.yaml
F: Documentation/devicetree/bindings/regulator/da92*.txt
F: Documentation/devicetree/bindings/regulator/slg51000.txt
--
2.37.1
There's no such thing of using the same kernel-doc markup for multiple
functions. Trying to be creative using a single one with a comma meant
for it to serve two functions will do the wrong thing and produce a
warning:
./include/linux/dcache.h:310: warning: expecting prototype for dget, dget_dlock(). Prototype was for dget_dlock() instead
Address it by duplicating the comment.
Yet, it probably makes sense to explain when/why someone has to use
each variant of it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
include/linux/dcache.h | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index 92c78ed02b54..5f254284bb83 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -299,7 +299,7 @@ extern char *dentry_path(const struct dentry *, char *, int);
/* Allocation counts.. */
/**
- * dget, dget_dlock - get a reference to a dentry
+ * dget_dlock - get a reference to a dentry
* @dentry: dentry to get a reference to
*
* Given a dentry or %NULL pointer increment the reference count
@@ -313,6 +313,14 @@ static inline struct dentry *dget_dlock(struct dentry *dentry)
return dentry;
}
+/**
+ * dget - get a reference to a dentry
+ * @dentry: dentry to get a reference to
+ *
+ * Given a dentry or %NULL pointer increment the reference count
+ * if appropriate and return the dentry. A dentry will not be
+ * destroyed when it has references.
+ */
static inline struct dentry *dget(struct dentry *dentry)
{
if (dentry)
--
2.37.1
The "::" tag requires a blank line after it, as otherwise, it won't be
processed.
Fix this warning:
Documentation/ABI/testing/sysfs-bus-nvdimm:11: WARNING: Unexpected indentation.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
Documentation/ABI/testing/sysfs-bus-nvdimm | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm
index 1c1f5acbf53d..eeabba807e4b 100644
--- a/Documentation/ABI/testing/sysfs-bus-nvdimm
+++ b/Documentation/ABI/testing/sysfs-bus-nvdimm
@@ -18,9 +18,11 @@ Description: (RO) Attribute group to describe the magic bits
Each attribute under this group defines a bit range of the
perf_event_attr.config. Supported attribute is listed
below::
+
event = "config:0-4" - event ID
For example::
+
ctl_res_cnt = "event=0x1"
What: /sys/bus/event_source/devices/nmemX/events
--
2.37.1
This file is outdated as the original document was removed. So, drop
it too.
Fixes: 9db370de2780 ("docs: process: remove outdated submitting-drivers.rst")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
.../translations/ja_JP/SubmittingPatches | 722 ------------------
1 file changed, 722 deletions(-)
delete mode 100644 Documentation/translations/ja_JP/SubmittingPatches
diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches
deleted file mode 100644
index 66ce0d8b0526..000000000000
--- a/Documentation/translations/ja_JP/SubmittingPatches
+++ /dev/null
@@ -1,722 +0,0 @@
-NOTE:
-This is a version of Documentation/process/submitting-patches.rst into Japanese.
-This document is maintained by Keiichi KII <[email protected]>
-and the JF Project team <http://www.linux.or.jp/JF/>.
-If you find any difference between this document and the original file
-or a problem with the translation,
-please contact the maintainer of this file or JF project.
-
-Please also note that the purpose of this file is to be easier to read
-for non English (read: Japanese) speakers and is not intended as a
-fork. So if you have any comments or updates of this file, please try
-to update the original English file first.
-
-Last Updated: 2011/06/09
-
-==================================
-これは、
-linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
-です。
-翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
-翻訳日： 2011/06/09
-翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
-校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
- Matsukura さん <nbh--mats at nifty dot com>
- Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp>
-==================================
-
- Linux カーネルに変更を加えるための Howto
- 又は
- かの Linus Torvalds の取り扱い説明書
-
-Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
-チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
-おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
-てもらえやすくする提案を集めたものです。
-
-コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
-を通してチェックしてください。もしあなたがドライバーを投稿しようとし
-ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。
-
---------------------------------------------
-セクション1 パッチの作り方と送り方
---------------------------------------------
-
-1) 「 diff -up 」
-------------
-
-パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
-
-Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
-生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
-数を指定して、unified 形式のパッチを作成することを確認してください。また、
-変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
-この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
-カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
-ディレクトリを基準にしないといけません。
-
-1個のファイルについてのパッチを作成するためには、ほとんどの場合、
-以下の作業を行えば十分です。
-
- SRCTREE=linux-2.6
- MYFILE=drivers/net/mydriver.c
-
- cd $SRCTREE
- cp $MYFILE $MYFILE.orig
- vi $MYFILE # make your change
- cd ..
- diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
-なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
-ソースとの差分を生成しないといけません。例えば、
-
- MYSRC=/devel/linux-2.6
-
- tar xvfz linux-2.6.12.tar.gz
- mv linux-2.6.12 linux-2.6.12-vanilla
- diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
- linux-2.6.12-vanilla $MYSRC > /tmp/patch
-
-dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
-ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
-コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
-ンの Linux カーネルソースツリーに含まれています。
-
-投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
-認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
-りのものであることを確認してください。
-
-もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
-を意味のあるひとまとまりごとに分けたいと思うかもしれません。
-これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
-パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
-る多くのスクリプトがあります。
-
-Quilt:
-http://savannah.nongnu.org/projects/quilt
-
-2) パッチに対する説明
-
-パッチの中の変更点に対する技術的な詳細について説明してください。
-
-説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
-「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
-テム X に対する更新を含んでいます。どうか取り入れてください。」などです。
-
-パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の
-コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。
-以下の #15 を見てください。
-
-説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
-という兆候です。次の #3 を見てください。
-
-パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を
-パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ
-書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを
-パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する
-手間をかけさせないでください。
-つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする
-人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく
-過去のバージョンのパッチを受け取ってもいない人がいます。
-
-登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID
-や URL を明記してください。
-
-特定のコミットを参照したい場合は、その SHA-1 ID だけでなく、一行サマリ
-も含めてください。それにより、それが何に関するコミットなのかがレビューする
-人にわかりやすくなります。
-例 (英文のママ):
-
- Commit e21d2170f36602ae2708 ("video: remove unnecessary
- platform_set_drvdata()") removed the unnecessary
- platform_set_drvdata(), but left the variable "dev" unused,
- delete it.
-
-
-3) パッチの分割
-
-意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。
-
-例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
-化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
-けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
-ドライバーが含まれているなら、2つのパッチに分けてください。
-
-一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
-るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
-意味的に同じ1つの変更は1つのパッチの中に含まれます。
-
-あるパッチが変更を完結させるために他のパッチに依存していたとしても、
-それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
-している」と簡単に注意書きをつけてください。
-
-もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
-15かそこらのパッチを送り、そのレビューと統合を待って下さい。
-
-4) パッチのスタイルチェック
-
-あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
-ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で
-見つけることができます。コーディングスタイルの違反はレビューする人の
-時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
-拒否されるでしょう。
-
-あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
-( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。
-もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
-理由を示せるようにしておく必要があります。
-
-5) 電子メールの宛先の選び方
-
-MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
-更がメンテナのいる特定のサブシステムに加えられるものであることが分か
-れば、その人に電子メールを送ってください。その際
-./scripts/get_maintainers.pl のスクリプトが有用です。
-
-もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
-LKML ( [email protected] )へパッチを送ってください。ほとんど
-のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
-コメントを得ることができます。
-
-15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
-いでください!!!
-
-Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
-です。電子メールアドレスは [email protected] になります。彼は
-多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
-避けるべきです。
-
-バグフィックスであったり、自明な変更であったり、話し合いをほとんど
-必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
-話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
-は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
-Linus へ送るべきです。
-
-6) CC (カーボンコピー)先の選び方
-
-特に理由がないなら、LKML にも CC してください。
-
-Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
-の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
-るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
-リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
-ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
-の変更に、はっきりと関連のあるメーリングリストについて知りたければ
-MAINTAINERS ファイルを参照してください。
-
-VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
-サイトに載っています。
-<http://vger.kernel.org/vger-lists.html>
-
-もし、変更がユーザランドのカーネルインタフェースに影響を与え
-るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
-があります)に man ページのパッチを送ってください。少なくとも
-情報がマニュアルページの中に入ってくるように、変更が起きたという
-通知を送ってください。
-
-たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を
-加えたときには、いつもメンテナに CC するのを忘れないようにしてください。
-
-
-7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ
-
-Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
-る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
-部分にコメントをするために、標準的な電子メールクライアントで変更が引用
-できることは重要です。
-
-上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
-れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
-チを改悪するエディターの折り返し機能に注意してください。
-
-パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
-ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
-キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
-イアントがコードに対するコメントを付けることをできなくします。また、
-MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
-受け入れてもらう可能性が低くなってしまいます。
-
-例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
-あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
-
-余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
-のヒントについては Documentation/process/email-clients.rst を参照してください。
-
-8) 電子メールのサイズ
-
-パッチを Linus へ送るときは常に #7 の手順に従ってください。
-
-大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
-未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な
-サーバに保存し、保存場所を示す URL を伝えるほうが適切です。
-
-9) カーネルバージョンの明記
-
-パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
-サブジェクトに付けることが重要です。
-
-パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
-そのパッチを採用しないでしょう。
-
-10) がっかりせず再投稿
-
-パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
-チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
-の中で姿を見せるでしょう。
-
-しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
-理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
-したパッチを投稿するのはあなたの仕事です。
-
-Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
-て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
-け取っていないのであれば、以下の理由が考えられます。
-* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
-* パッチが LKML で十分に議論されていなかった
-* スタイルの問題(セクション2を参照)
-* 電子メールフォーマットの問題(このセクションを参照)
-* パッチに対する技術的な問題
-* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
- 失った
-* 不愉快にさせている
-
-判断できない場合は、LKML にコメントを頼んでください。
-
-11) サブジェクトに「 PATCH 」
-
-Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
-「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
-カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
-かをより簡単に識別できます。
-
-12) パッチへの署名
-
-誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
-メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
-メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
-ました。
-
-「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
-あなたがそのパッチをオープンソースとして提供する権利を保持している、
-という証明をパッチの説明の末尾に一行記載するというものです。
-ルールはとても単純です。以下の項目を確認して下さい。
-
- 原作者の証明書( DCO ) 1.1
-
- このプロジェクトに寄与するものとして、以下のことを証明する。
-
- (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
- ル中に明示されたオープンソースライセンスの下で公開する権利
- を持っている。もしくは、
-
- (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
- ーされている既存の作品を元にしている。同時に、私はそのライセ
- ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
- される同一のオープンソースライセンスで(異なるライセンスの下で
- 投稿することが許可されている場合を除いて)投稿する権利を持って
- いる。もしくは、
-
- (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
- ものであり、私はそれに変更を加えていない。
-
- (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
- る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
- 含む)が無期限に保全されることと、当該プロジェクト又は関連する
- オープンソースライセンスに沿った形で再配布されることに理解及び
- 同意する。
-
-もしこれに同意できるなら、以下のような1行を追加してください。
-
- Signed-off-by: Random J Developer <[email protected]>
-
-実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)
-
-人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
-無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
-な情報を示したりすることができます。
-
-あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の
-ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら
-あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。
-もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を
-とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する
-ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。
-しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう
-ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の
-Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を
-加えたことを示す1行を追加することが推奨されています。
-(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名
-と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに
-あることを明確にするのに十分な方法のようです。例えば、
-
- Signed-off-by: Random J Developer <[email protected]>
- [[email protected]: struct foo moved from foo.c to foo.h]
- Signed-off-by: Lucky K Maintainer <[email protected]>
-
-あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、
-修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に
-有用となります。いかなる事情があってもチェンジログに出てくる作成者の
-アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。
-
-バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット
-メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する
-ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。
-
- Date: Tue May 13 19:10:30 2008 +0000
-
- SCSI: libiscsi regression in 2.6.25: fix nop timer handling
-
- commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
-
-そして、これは 2.4 ツリーでの一例です。
-
- Date: Tue May 13 22:12:27 2008 +0200
-
- wireless, airo: waitbusy() won't delay
-
- [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
-
-どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを
-解決しようとしている人にとって価値のある支援となります。
-
-13) いつ Acked-by: と Cc: を使うのか
-
-「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
-の伝播パスにいたことを示しています。
-
-ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
-る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
-えます。Acked-by: はパッチのチェンジログにも追加されます。
-
-パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
-の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。
-
-Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
-少なくともパッチをレビューし、同意を示しているという記録です。そのような
-ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を
-Acked-by: へ置き換えることがあります。
-
-Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
-あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
-のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
-そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
-この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
-メーリングリストアーカイブの中の大元の議論を参照すべきです。
-
-パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、
-その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの
-明確なアクションなしに付与できる唯一のタグです。
-このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと
-を明文化します。
-
-14) Reported-by:, Tested-by:, Reviewed-by: および Suggested-by: の利用
-
-他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を
-クレジットするために、Reported-by: タグを追加することを検討してください。
-こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び
-コミュニティの力となってくれるでしょう。
-ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、
-問題が公の場で報告されていなかったのであれば。
-
-Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功
-していることを示します。このタグはメンテナにテストが実施済みであることを
-知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に
-対するクレジットを保証します。
-
-Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、
-受け入れ可能とみなされたパッチであることを示します。
-
- レビューアによる監督宣言
-
- 私は Reviewed-by: タグを提示することによって、以下のことを明言する。
-
- (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性
- (訳注)」を検証し、技術的側面からパッチをレビュー済みである。
-
- 訳注:
- 「即応性」の原文は "readiness"。
- パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に
- 行うことができる状態であるかどうかを "readiness" という単語で表現
- している。
-
- (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み
- である。私はそれらのコメントに対する投稿者の返答に満足している。
-
- (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが
- カーネルにとって価値のある変更であること、そして、(2)統合に際して
- 議論になり得るような問題はないものと確信している。
-
- (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる
- 状況においてその宣言した目的や機能が正しく実現することに関して、
- いかなる保証もしない(特にどこかで明示しない限り)。
-
-Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的
-問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー
-作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは
-レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに
-知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした
-レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの
-パッチをカーネルにマージする可能性を高めるでしょう。
-
-Suggested-by: タグは、パッチのアイデアがその人からの提案に基づくものである
-ことを示し、アイデアの提供をクレジットするものです。提案者の明示的な許可が
-ない場合、特にそのアイデアが公開のフォーラムで示されていない場合には、この
-タグをつけないように注意してください。とはいえ、アイデアの提供者をこつこつ
-クレジットしていけば、望むらくはその人たちが将来別の機会に再度力を貸す気に
-なってくれるかもしれません。
-
-15) 標準的なパッチのフォーマット
-
-標準的なパッチのサブジェクトは以下のとおりです。
-
- Subject: [PATCH 001/123] subsystem: summary phrase
-
-標準的なパッチの、電子メールのボディは以下の項目を含んでいます。
-
- - パッチの作成者を明記する「 from 」行
-
- - 空行
-
- - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
- (変更履歴)にコピーされます。
-
- - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
- ジログ内にコピーされます。
-
- - マーカー行は単純に「 --- 」です。
-
- - 余計なコメントは、チェンジログには不適切です。
-
- - 実際のパッチ(差分出力)
-
-サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
-ソートしやすいものになっています。(ほとんどの電子メールクライアント
-はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
-るため、数字でのソートとアルファベットでのソートは同じ結果になります。
-
-電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
-分野またはサブシステムを識別できるようにすべきです。
-
-電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確
-に表現しなければなりません。「summary phrase」をファイル名にしてはい
-けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を
-使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の
-パッチ群です)。
-
-あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に
-なるように心がけてください。「summary phrase」は git のチェンジログの中へ
-ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する
-ために議論の中で利用するかもしれません。
-人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で
-検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や
-「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、
-唯一目にとまる情報となるでしょう。
-
-これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を
-変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。
-「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく
-まとめられている概要となるべきです。
-
-「summary phrase」は「Subject: [PATCH tag] <summary phrase>」のように、
-大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは
-「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを
-表現します。
-一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する
-コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、
-「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの
-パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても
-かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。
-そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは
-適用するのを保証するためです。
-
-サブジェクトの例を二つ
-
- Subject: [patch 2/5] ext2: improve scalability of bitmap searching
- Subject: [PATCHv2 001/207] x86: fix eflags tracking
-
-「 from 」行は電子メールのボディの一番最初の行でなければなりません。
-その形式は以下のとおりです。
-
- From: Original Author <[email protected]>
-
-「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
-ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
-ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
-れるでしょう。
-
-説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
-本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
-がその詳細を思い出すことができるものでなければなりません。パッチが対処する
-障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に
-対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。
-パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける
-ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は
-ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。
-
-「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
-部分を認識させるという重要な役目を果たします。
-
-「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
-があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
-追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
-おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
-は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
-ようなコメントもマーカー行の後に書かれるべきです。
-このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを
-表す「パッチの変更履歴」が挙げられます。
-
-「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル
-名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向
-のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」
-を指定してください(インデントを含めてちょうど80列に合うでしょう)。
-
-適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
-ください。
-
-16) 「git pull」要求の送り方(Linus の電子メールから)
-
-間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと
-ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック
-で全て選択できます。
-
-正しい形式は下記の通りです。
-
- "Please pull from
-
- git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
-
- to get these changes:"
-
-その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、
-何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を
-検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを
-「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が
-なくなればより快適になるでしょう)。
-
-diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って
-ください。-M オプションはファイル名の変更を検知でき、--summary オプションは
-新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。
-
--M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり
-異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
-判断するためです。
-
-------------------------------------
-セクション2 - ヒントとTIPSと小技
-------------------------------------
-
-このセクションは Linux カーネルに変更を適用することに関係のある一般的な
-「お約束」の多くを載せています。物事には例外というものがあります。しか
-し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
-セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
-
-1) Documentation/process/coding-style.rstを参照
-
-言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
-も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
-れません。
-
-特筆すべき例外は、コードをあるファイルから別のファイルに移動
-するときです。この場合、コードを移動するパッチでは、移動されるコード
-に関して移動以外の変更を一切加えるべきではありません。これにより、
-コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
-ります。これは実際に何が変更されたかをレビューする際の大きな助けに
-なるとともに、ツールにコードの履歴を追跡させることも容易になります。
-
-投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
-あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
-論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
-はしているが修正するより良く見えるのであれば、おそらくそのままにする
-のがベストです。
-
-スタイルチェッカーによる3段階のレポート:
- - エラー: 間違っている可能性が高い
- - 警告：注意してレビューする必要がある
- - チェック：考慮する必要がある
-
-あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
-理由を示せるようにしておく必要があります。
-
-2) #ifdefは見苦しい
-
-ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
-で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
-条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
-てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
-しょう。
-
-まずいコードの簡単な例
-
- dev = alloc_etherdev (sizeof(struct funky_private));
- if (!dev)
- return -ENODEV;
- #ifdef CONFIG_NET_FUNKINESS
- init_funky_net(dev);
- #endif
-
-クリーンアップしたコードの例
-
-(in header)
- #ifndef CONFIG_NET_FUNKINESS
- static inline void init_funky_net (struct net_device *d) {}
- #endif
-
-(in the code itself)
- dev = alloc_etherdev (sizeof(struct funky_private));
- if (!dev)
- return -ENODEV;
- init_funky_net(dev);
-
-3) マクロより「 static inline 」を推奨
-
-「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
-型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
-gcc においては、マクロと同じくらい軽いです。
-
-マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
-いくつかの特定のケース)や「 static inline 」関数を使うことができないような
-場所(マクロの引数の文字列連結のような)にだけ使われるべきです。
-
-「 static inline 」は「 static __inline__ 」や「 extern inline 」や
-「 extern __inline__ 」よりも適切です。
-
-4) 設計に凝りすぎるな
-
-それが有用になるかどうか分からないような不明瞭な将来を見越した設計
-をしないでください。「できる限り簡単に、そして、それ以上簡単になら
-ないような設計をしてください。」
-
-----------------------
-セクション3 参考文献
-----------------------
-
-Andrew Morton, "The perfect patch" (tpp).
- <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
-
-Jeff Garzik, "Linux kernel patch submission format".
- <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
-
-Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
- <http://www.kroah.com/log/linux/maintainer.html>
- <http://www.kroah.com/log/linux/maintainer-02.html>
- <http://www.kroah.com/log/linux/maintainer-03.html>
- <http://www.kroah.com/log/linux/maintainer-04.html>
- <http://www.kroah.com/log/linux/maintainer-05.html>
-
-NO!!!! No more huge patch bombs to [email protected] people!
- <https://lore.kernel.org/r/[email protected]>
-
-Kernel Documentation/process/coding-style.rst:
- <http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst>
-
-Linus Torvalds's mail on the canonical patch format:
- <https://lore.kernel.org/r/[email protected]>
-
-Andi Kleen, "On submitting kernel patches"
- Some strategies to get difficult or controversial changes in.
- http://halobates.de/on-submitting-patches.pdf
-
---
-
-
--
2.37.1
Hi Mauro,
On Thu, 18 Aug 2022 15:38:49 +0200, Mauro Carvalho Chehab wrote:
> This file is outdated as the original document was removed. So, drop
> it too.
>
> Fixes: 9db370de2780 ("docs: process: remove outdated submitting-drivers.rst")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Yes, this is quite outdated, but a change set was merged recently during
the v5.19 merge window [1, 2].
Please keep it and the other outdated files under ja_JP/ so that I
can continue updating them!
[1]: e29b3abcb2b6 ("docs/ja_JP/SubmittingPatches: Request summaries for commit references")
[2]: https://lore.kernel.org/linux-doc/[email protected]/
Thanks, Akira
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> .../translations/ja_JP/SubmittingPatches | 722 ------------------
> 1 file changed, 722 deletions(-)
> delete mode 100644 Documentation/translations/ja_JP/SubmittingPatches
>
> diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches
> deleted file mode 100644
> index 66ce0d8b0526..000000000000
> --- a/Documentation/translations/ja_JP/SubmittingPatches
> +++ /dev/null
> @@ -1,722 +0,0 @@
> -NOTE:
> -This is a version of Documentation/process/submitting-patches.rst into Japanese.
> -This document is maintained by Keiichi KII <[email protected]>
> -and the JF Project team <http://www.linux.or.jp/JF/>.
> -If you find any difference between this document and the original file
> -or a problem with the translation,
> -please contact the maintainer of this file or JF project.
> -
> -Please also note that the purpose of this file is to be easier to read
> -for non English (read: Japanese) speakers and is not intended as a
> -fork. So if you have any comments or updates of this file, please try
> -to update the original English file first.
> -
> -Last Updated: 2011/06/09
> -
> -==================================
> -これは、
> -linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
> -です。
> -翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
> -翻訳日： 2011/06/09
> -翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
> -校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
> - Matsukura さん <nbh--mats at nifty dot com>
> - Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp>
> -==================================
> -
> - Linux カーネルに変更を加えるための Howto
> - 又は
> - かの Linus Torvalds の取り扱い説明書
> -
> -Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
> -チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
> -おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
> -てもらえやすくする提案を集めたものです。
> -
> -コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
> -を通してチェックしてください。もしあなたがドライバーを投稿しようとし
> -ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。
> -
> ---------------------------------------------
> -セクション1 パッチの作り方と送り方
> ---------------------------------------------
> -
> -1) 「 diff -up 」
> -------------
> -
> -パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
> -
> -Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
> -生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
> -数を指定して、unified 形式のパッチを作成することを確認してください。また、
> -変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
> -この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
> -カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
> -ディレクトリを基準にしないといけません。
> -
> -1個のファイルについてのパッチを作成するためには、ほとんどの場合、
> -以下の作業を行えば十分です。
> -
> - SRCTREE=linux-2.6
> - MYFILE=drivers/net/mydriver.c
> -
> - cd $SRCTREE
> - cp $MYFILE $MYFILE.orig
> - vi $MYFILE # make your change
> - cd ..
> - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
> -
> -複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
> -なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
> -ソースとの差分を生成しないといけません。例えば、
> -
> - MYSRC=/devel/linux-2.6
> -
> - tar xvfz linux-2.6.12.tar.gz
> - mv linux-2.6.12 linux-2.6.12-vanilla
> - diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
> - linux-2.6.12-vanilla $MYSRC > /tmp/patch
> -
> -dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
> -ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
> -コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
> -ンの Linux カーネルソースツリーに含まれています。
> -
> -投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
> -認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
> -りのものであることを確認してください。
> -
> -もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
> -を意味のあるひとまとまりごとに分けたいと思うかもしれません。
> -これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
> -パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
> -る多くのスクリプトがあります。
> -
> -Quilt:
> -http://savannah.nongnu.org/projects/quilt
> -
> -2) パッチに対する説明
> -
> -パッチの中の変更点に対する技術的な詳細について説明してください。
> -
> -説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
> -「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
> -テム X に対する更新を含んでいます。どうか取り入れてください。」などです。
> -
> -パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の
> -コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。
> -以下の #15 を見てください。
> -
> -説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
> -という兆候です。次の #3 を見てください。
> -
> -パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を
> -パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ
> -書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを
> -パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する
> -手間をかけさせないでください。
> -つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする
> -人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく
> -過去のバージョンのパッチを受け取ってもいない人がいます。
> -
> -登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID
> -や URL を明記してください。
> -
> -特定のコミットを参照したい場合は、その SHA-1 ID だけでなく、一行サマリ
> -も含めてください。それにより、それが何に関するコミットなのかがレビューする
> -人にわかりやすくなります。
> -例 (英文のママ):
> -
> - Commit e21d2170f36602ae2708 ("video: remove unnecessary
> - platform_set_drvdata()") removed the unnecessary
> - platform_set_drvdata(), but left the variable "dev" unused,
> - delete it.
> -
> -
> -3) パッチの分割
> -
> -意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。
> -
> -例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
> -化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
> -けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
> -ドライバーが含まれているなら、2つのパッチに分けてください。
> -
> -一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
> -るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
> -意味的に同じ1つの変更は1つのパッチの中に含まれます。
> -
> -あるパッチが変更を完結させるために他のパッチに依存していたとしても、
> -それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
> -している」と簡単に注意書きをつけてください。
> -
> -もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
> -15かそこらのパッチを送り、そのレビューと統合を待って下さい。
> -
> -4) パッチのスタイルチェック
> -
> -あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
> -ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で
> -見つけることができます。コーディングスタイルの違反はレビューする人の
> -時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
> -拒否されるでしょう。
> -
> -あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
> -( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。
> -もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
> -理由を示せるようにしておく必要があります。
> -
> -5) 電子メールの宛先の選び方
> -
> -MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
> -更がメンテナのいる特定のサブシステムに加えられるものであることが分か
> -れば、その人に電子メールを送ってください。その際
> -./scripts/get_maintainers.pl のスクリプトが有用です。
> -
> -もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
> -LKML ( [email protected] )へパッチを送ってください。ほとんど
> -のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
> -コメントを得ることができます。
> -
> -15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
> -いでください!!!
> -
> -Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
> -です。電子メールアドレスは [email protected] になります。彼は
> -多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
> -避けるべきです。
> -
> -バグフィックスであったり、自明な変更であったり、話し合いをほとんど
> -必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
> -話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
> -は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
> -Linus へ送るべきです。
> -
> -6) CC (カーボンコピー)先の選び方
> -
> -特に理由がないなら、LKML にも CC してください。
> -
> -Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
> -の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
> -るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
> -リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
> -ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
> -の変更に、はっきりと関連のあるメーリングリストについて知りたければ
> -MAINTAINERS ファイルを参照してください。
> -
> -VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
> -サイトに載っています。
> -<http://vger.kernel.org/vger-lists.html>
> -
> -もし、変更がユーザランドのカーネルインタフェースに影響を与え
> -るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
> -があります)に man ページのパッチを送ってください。少なくとも
> -情報がマニュアルページの中に入ってくるように、変更が起きたという
> -通知を送ってください。
> -
> -たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を
> -加えたときには、いつもメンテナに CC するのを忘れないようにしてください。
> -
> -
> -7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ
> -
> -Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
> -る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
> -部分にコメントをするために、標準的な電子メールクライアントで変更が引用
> -できることは重要です。
> -
> -上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
> -れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
> -チを改悪するエディターの折り返し機能に注意してください。
> -
> -パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
> -ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
> -キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
> -イアントがコードに対するコメントを付けることをできなくします。また、
> -MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
> -受け入れてもらう可能性が低くなってしまいます。
> -
> -例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
> -あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
> -
> -余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
> -のヒントについては Documentation/process/email-clients.rst を参照してください。
> -
> -8) 電子メールのサイズ
> -
> -パッチを Linus へ送るときは常に #7 の手順に従ってください。
> -
> -大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
> -未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な
> -サーバに保存し、保存場所を示す URL を伝えるほうが適切です。
> -
> -9) カーネルバージョンの明記
> -
> -パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
> -サブジェクトに付けることが重要です。
> -
> -パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
> -そのパッチを採用しないでしょう。
> -
> -10) がっかりせず再投稿
> -
> -パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
> -チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
> -の中で姿を見せるでしょう。
> -
> -しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
> -理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
> -したパッチを投稿するのはあなたの仕事です。
> -
> -Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
> -て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
> -け取っていないのであれば、以下の理由が考えられます。
> -* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
> -* パッチが LKML で十分に議論されていなかった
> -* スタイルの問題(セクション2を参照)
> -* 電子メールフォーマットの問題(このセクションを参照)
> -* パッチに対する技術的な問題
> -* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
> - 失った
> -* 不愉快にさせている
> -
> -判断できない場合は、LKML にコメントを頼んでください。
> -
> -11) サブジェクトに「 PATCH 」
> -
> -Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
> -「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
> -カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
> -かをより簡単に識別できます。
> -
> -12) パッチへの署名
> -
> -誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
> -メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
> -メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
> -ました。
> -
> -「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
> -あなたがそのパッチをオープンソースとして提供する権利を保持している、
> -という証明をパッチの説明の末尾に一行記載するというものです。
> -ルールはとても単純です。以下の項目を確認して下さい。
> -
> - 原作者の証明書( DCO ) 1.1
> -
> - このプロジェクトに寄与するものとして、以下のことを証明する。
> -
> - (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
> - ル中に明示されたオープンソースライセンスの下で公開する権利
> - を持っている。もしくは、
> -
> - (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
> - ーされている既存の作品を元にしている。同時に、私はそのライセ
> - ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
> - される同一のオープンソースライセンスで(異なるライセンスの下で
> - 投稿することが許可されている場合を除いて)投稿する権利を持って
> - いる。もしくは、
> -
> - (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
> - ものであり、私はそれに変更を加えていない。
> -
> - (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
> - る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
> - 含む)が無期限に保全されることと、当該プロジェクト又は関連する
> - オープンソースライセンスに沿った形で再配布されることに理解及び
> - 同意する。
> -
> -もしこれに同意できるなら、以下のような1行を追加してください。
> -
> - Signed-off-by: Random J Developer <[email protected]>
> -
> -実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)
> -
> -人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
> -無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
> -な情報を示したりすることができます。
> -
> -あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の
> -ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら
> -あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。
> -もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を
> -とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する
> -ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。
> -しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう
> -ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の
> -Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を
> -加えたことを示す1行を追加することが推奨されています。
> -(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名
> -と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに
> -あることを明確にするのに十分な方法のようです。例えば、
> -
> - Signed-off-by: Random J Developer <[email protected]>
> - [[email protected]: struct foo moved from foo.c to foo.h]
> - Signed-off-by: Lucky K Maintainer <[email protected]>
> -
> -あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、
> -修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に
> -有用となります。いかなる事情があってもチェンジログに出てくる作成者の
> -アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。
> -
> -バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット
> -メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する
> -ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。
> -
> - Date: Tue May 13 19:10:30 2008 +0000
> -
> - SCSI: libiscsi regression in 2.6.25: fix nop timer handling
> -
> - commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
> -
> -そして、これは 2.4 ツリーでの一例です。
> -
> - Date: Tue May 13 22:12:27 2008 +0200
> -
> - wireless, airo: waitbusy() won't delay
> -
> - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
> -
> -どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを
> -解決しようとしている人にとって価値のある支援となります。
> -
> -13) いつ Acked-by: と Cc: を使うのか
> -
> -「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
> -の伝播パスにいたことを示しています。
> -
> -ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
> -る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
> -えます。Acked-by: はパッチのチェンジログにも追加されます。
> -
> -パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
> -の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。
> -
> -Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
> -少なくともパッチをレビューし、同意を示しているという記録です。そのような
> -ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を
> -Acked-by: へ置き換えることがあります。
> -
> -Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
> -あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
> -のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
> -そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
> -この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
> -メーリングリストアーカイブの中の大元の議論を参照すべきです。
> -
> -パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、
> -その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの
> -明確なアクションなしに付与できる唯一のタグです。
> -このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと
> -を明文化します。
> -
> -14) Reported-by:, Tested-by:, Reviewed-by: および Suggested-by: の利用
> -
> -他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を
> -クレジットするために、Reported-by: タグを追加することを検討してください。
> -こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び
> -コミュニティの力となってくれるでしょう。
> -ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、
> -問題が公の場で報告されていなかったのであれば。
> -
> -Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功
> -していることを示します。このタグはメンテナにテストが実施済みであることを
> -知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に
> -対するクレジットを保証します。
> -
> -Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、
> -受け入れ可能とみなされたパッチであることを示します。
> -
> - レビューアによる監督宣言
> -
> - 私は Reviewed-by: タグを提示することによって、以下のことを明言する。
> -
> - (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性
> - (訳注)」を検証し、技術的側面からパッチをレビュー済みである。
> -
> - 訳注:
> - 「即応性」の原文は "readiness"。
> - パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に
> - 行うことができる状態であるかどうかを "readiness" という単語で表現
> - している。
> -
> - (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み
> - である。私はそれらのコメントに対する投稿者の返答に満足している。
> -
> - (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが
> - カーネルにとって価値のある変更であること、そして、(2)統合に際して
> - 議論になり得るような問題はないものと確信している。
> -
> - (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる
> - 状況においてその宣言した目的や機能が正しく実現することに関して、
> - いかなる保証もしない(特にどこかで明示しない限り)。
> -
> -Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的
> -問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー
> -作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは
> -レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに
> -知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした
> -レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの
> -パッチをカーネルにマージする可能性を高めるでしょう。
> -
> -Suggested-by: タグは、パッチのアイデアがその人からの提案に基づくものである
> -ことを示し、アイデアの提供をクレジットするものです。提案者の明示的な許可が
> -ない場合、特にそのアイデアが公開のフォーラムで示されていない場合には、この
> -タグをつけないように注意してください。とはいえ、アイデアの提供者をこつこつ
> -クレジットしていけば、望むらくはその人たちが将来別の機会に再度力を貸す気に
> -なってくれるかもしれません。
> -
> -15) 標準的なパッチのフォーマット
> -
> -標準的なパッチのサブジェクトは以下のとおりです。
> -
> - Subject: [PATCH 001/123] subsystem: summary phrase
> -
> -標準的なパッチの、電子メールのボディは以下の項目を含んでいます。
> -
> - - パッチの作成者を明記する「 from 」行
> -
> - - 空行
> -
> - - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
> - (変更履歴)にコピーされます。
> -
> - - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
> - ジログ内にコピーされます。
> -
> - - マーカー行は単純に「 --- 」です。
> -
> - - 余計なコメントは、チェンジログには不適切です。
> -
> - - 実際のパッチ(差分出力)
> -
> -サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
> -ソートしやすいものになっています。(ほとんどの電子メールクライアント
> -はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
> -るため、数字でのソートとアルファベットでのソートは同じ結果になります。
> -
> -電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
> -分野またはサブシステムを識別できるようにすべきです。
> -
> -電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確
> -に表現しなければなりません。「summary phrase」をファイル名にしてはい
> -けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を
> -使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の
> -パッチ群です)。
> -
> -あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に
> -なるように心がけてください。「summary phrase」は git のチェンジログの中へ
> -ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する
> -ために議論の中で利用するかもしれません。
> -人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で
> -検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や
> -「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、
> -唯一目にとまる情報となるでしょう。
> -
> -これらの理由の��め、「summary phrase」はなぜパッチが必要であるか、パッチが何を
> -変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。
> -「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく
> -まとめられている概要となるべきです。
> -
> -「summary phrase」は「Subject: [PATCH tag] <summary phrase>」のように、
> -大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは
> -「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを
> -表現します。
> -一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する
> -コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、
> -「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの
> -パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても
> -かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。
> -そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは
> -適用するのを保証するためです。
> -
> -サブジェクトの例を二つ
> -
> - Subject: [patch 2/5] ext2: improve scalability of bitmap searching
> - Subject: [PATCHv2 001/207] x86: fix eflags tracking
> -
> -「 from 」行は電子メールのボディの一番最初の行でなければなりません。
> -その形式は以下のとおりです。
> -
> - From: Original Author <[email protected]>
> -
> -「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
> -ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
> -ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
> -れるでしょう。
> -
> -説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
> -本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
> -がその詳細を思い出すことができるものでなければなりません。パッチが対処する
> -障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に
> -対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。
> -パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける
> -ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は
> -ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。
> -
> -「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
> -部分を認識させるという重要な役目を果たします。
> -
> -「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
> -があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
> -追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
> -おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
> -は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
> -ようなコメントもマーカー行の後に書かれるべきです。
> -このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを
> -表す「パッチの変更履歴」が挙げられます。
> -
> -「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル
> -名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向
> -のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」
> -を指定してください(インデントを含めてちょうど80列に合うでしょう)。
> -
> -適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
> -ください。
> -
> -16) 「git pull」要求の送り方(Linus の電子メールから)
> -
> -間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと
> -ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック
> -で全て選択できます。
> -
> -正しい形式は下記の通りです。
> -
> - "Please pull from
> -
> - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
> -
> - to get these changes:"
> -
> -その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、
> -何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を
> -検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを
> -「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が
> -なくなればより快適になるでしょう)。
> -
> -diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って
> -ください。-M オプションはファイル名の変更を検知でき、--summary オプションは
> -新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。
> -
> --M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり
> -異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
> -判断するためです。
> -
> -------------------------------------
> -セクション2 - ヒントとTIPSと小技
> -------------------------------------
> -
> -このセクションは Linux カーネルに変更を適用することに関係のある一般的な
> -「お約束」の多くを載せています。物事には例外というものがあります。しか
> -し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
> -セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
> -
> -1) Documentation/process/coding-style.rstを参照
> -
> -言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
> -も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
> -れません。
> -
> -特筆すべき例外は、コードをあるファイルから別のファイルに移動
> -するときです。この場合、コードを移動するパッチでは、移動されるコード
> -に関して移動以外の変更を一切加えるべきではありません。これにより、
> -コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
> -ります。これは実際に何が変更されたかをレビューする際の大きな助けに
> -なるとともに、ツールにコードの履歴を追跡させることも容易になります。
> -
> -投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
> -あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
> -論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
> -はしているが修正するより良く見えるのであれば、おそらくそのままにする
> -のがベストです。
> -
> -スタイルチェッカーによる3段階のレポート:
> - - エラー: 間違っている可能性が高い
> - - 警告：注意してレビューする必要がある
> - - チェック：考慮する必要がある
> -
> -あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
> -理由を示せるようにしておく必要があります。
> -
> -2) #ifdefは見苦しい
> -
> -ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
> -で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
> -条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
> -てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
> -しょう。
> -
> -まずいコードの簡単な例
> -
> - dev = alloc_etherdev (sizeof(struct funky_private));
> - if (!dev)
> - return -ENODEV;
> - #ifdef CONFIG_NET_FUNKINESS
> - init_funky_net(dev);
> - #endif
> -
> -クリーンアップしたコードの例
> -
> -(in header)
> - #ifndef CONFIG_NET_FUNKINESS
> - static inline void init_funky_net (struct net_device *d) {}
> - #endif
> -
> -(in the code itself)
> - dev = alloc_etherdev (sizeof(struct funky_private));
> - if (!dev)
> - return -ENODEV;
> - init_funky_net(dev);
> -
> -3) マクロより「 static inline 」を推奨
> -
> -「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
> -型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
> -gcc においては、マクロと同じくらい軽いです。
> -
> -マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
> -いくつかの特定のケース)や「 static inline 」関数を使うことができないような
> -場所(マクロの引数の文字列連結のような)にだけ使われるべきです。
> -
> -「 static inline 」は「 static __inline__ 」や「 extern inline 」や
> -「 extern __inline__ 」よりも適切です。
> -
> -4) 設計に凝りすぎるな
> -
> -それが有用になるかどうか分からないような不明瞭な将来を見越した設計
> -をしないでください。「できる限り簡単に、そして、それ以上簡単になら
> -ないような設計をしてください。」
> -
> -----------------------
> -セクション3 参考文献
> -----------------------
> -
> -Andrew Morton, "The perfect patch" (tpp).
> - <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
> -
> -Jeff Garzik, "Linux kernel patch submission format".
> - <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
> -
> -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
> - <http://www.kroah.com/log/linux/maintainer.html>
> - <http://www.kroah.com/log/linux/maintainer-02.html>
> - <http://www.kroah.com/log/linux/maintainer-03.html>
> - <http://www.kroah.com/log/linux/maintainer-04.html>
> - <http://www.kroah.com/log/linux/maintainer-05.html>
> -
> -NO!!!! No more huge patch bombs to [email protected] people!
> - <https://lore.kernel.org/r/[email protected]>
> -
> -Kernel Documentation/process/coding-style.rst:
> - <http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst>
> -
> -Linus Torvalds's mail on the canonical patch format:
> - <https://lore.kernel.org/r/[email protected]>
> -
> -Andi Kleen, "On submitting kernel patches"
> - Some strategies to get difficult or controversial changes in.
> - http://halobates.de/on-submitting-patches.pdf
> -
> ---
> -
> -
On Thu, 18 Aug 2022 23:27:34 +0900, Akira Yokosawa wrote:
> Hi Mauro,
>
> On Thu, 18 Aug 2022 15:38:49 +0200, Mauro Carvalho Chehab wrote:
>> This file is outdated as the original document was removed. So, drop
>> it too.
>>
>> Fixes: 9db370de2780 ("docs: process: remove outdated submitting-drivers.rst")
>> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Yes, this is quite outdated, but a change set was merged recently during
> the v5.19 merge window [1, 2].
Uhm, it looks like you confused SubmittingPatches with submitting-drivers.rst
and are trying to remove SubmittingPatches, which should be kept...
Anyway, please don't remove it!
>
> Please keep it and the other outdated files under ja_JP/ so that I
> can continue updating them!
I'll submit a patch removing a ref to submitting-drivers.rst in it.
I didn't notice the dangling reference as the doc is still in plain-text.
Thanks, Akira
>
> [1]: e29b3abcb2b6 ("docs/ja_JP/SubmittingPatches: Request summaries for commit references")
> [2]: https://lore.kernel.org/linux-doc/[email protected]/
>
> Thanks, Akira
>
>> ---
[...]
On 8/18/22 20:38, Mauro Carvalho Chehab wrote:
> Address this warning:
> Documentation/leds/leds-qcom-lpg.rst: WARNING: o documento não está incluído em nenhum toctree
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/leds/index.rst | 1 +
> drivers/gpu/drm/scheduler/sched_main.c | 1 +
> include/drm/gpu_scheduler.h | 1 +
> 3 files changed, 3 insertions(+)
>
> diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
> index e5d63b940045..014e009b0761 100644
> --- a/Documentation/leds/index.rst
> +++ b/Documentation/leds/index.rst
> @@ -25,4 +25,5 @@ LEDs
> leds-lp5562
> leds-lp55xx
> leds-mlxcpld
> + leds-qcom-lpg
> leds-sc27xx
> diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
> index 68317d3a7a27..56c53a616816 100644
> --- a/drivers/gpu/drm/scheduler/sched_main.c
> +++ b/drivers/gpu/drm/scheduler/sched_main.c
> @@ -994,6 +994,7 @@ static int drm_sched_main(void *param)
> * used
> * @score: optional score atomic shared with other schedulers
> * @name: name used for debugging
> + * @dev: Device structure
> *
> * Return 0 on success, otherwise error code.
> */
> diff --git a/include/drm/gpu_scheduler.h b/include/drm/gpu_scheduler.h
> index addb135eeea6..f31988e03256 100644
> --- a/include/drm/gpu_scheduler.h
> +++ b/include/drm/gpu_scheduler.h
> @@ -435,6 +435,7 @@ struct drm_sched_backend_ops {
> * @_score: score used when the driver doesn't provide one
> * @ready: marks if the underlying HW is ready to work
> * @free_guilty: A hit to time out handler to free the guilty job.
> + * @dev: Device structure
> *
> * One scheduler is implemented for each hardware ring.
> */
Hi Mauro,
I have already sent the fix (resend a long time ago) at [1] and got
Acked-by from Pavel, but seems like he forgot to push it. Maybe the
subsystem had maintenanceship issue as pointed by Andy (CC'ed) ([2]).
[1]: https://lore.kernel.org/linux-doc/[email protected]/
[2]: https://lore.kernel.org/lkml/CAHp75VeWKgyz32scczN0c+iJwGZXVP42g0NG0oXrdJ34GyHB8w@mail.gmail.com/
Thanks.
--
An old man doll... just what I always wanted! - Clara
On 8/18/22 20:38, Mauro Carvalho Chehab wrote:
> Using wildcards for cross-reference doesn't work, as the Sphinx
> automarkup plugin is not smart enough. So, changeset
> c06475910b52 ("Documentation: coresight: Escape coresight bindings file wildcard")
> tried to fix it, but at the wrong way, as it the building system
> will keep producing warnings about that:
>
> Warning: Documentation/trace/coresight/coresight.rst references a file that doesn't exist: Documentation/devicetree/bindings/arm/arm,coresight-
>
> As automarkup will still try (and fail) to create a cross reference.
> So, instead, change the markup to ensure that the warning won't be
> reported.
>
> Fixes: c06475910b52 ("Documentation: coresight: Escape coresight bindings file wildcard")
> Cc: Bagas Sanjaya <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/trace/coresight/coresight.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 4a71ea6cb390..826e59a698da 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -130,7 +130,7 @@ Misc:
> Device Tree Bindings
> --------------------
>
> -See Documentation/devicetree/bindings/arm/arm,coresight-\*.yaml for details.
> +See ``Documentation/devicetree/bindings/arm/arm,coresight-*.yaml`` for details.
>
> As of this writing drivers for ITM, STMs and CTIs are not provided but are
> expected to be added as the solution matures.
This makes YAML wildcards be inline code. LGTM.
Acked-by: Bagas Sanjaya <[email protected]>
--
An old man doll... just what I always wanted! - Clara
On 18. 08. 22, 15:38, Mauro Carvalho Chehab wrote:
> Fix this doc build warning:
> ./include/linux/serial_core.h:397: warning: Function parameter or member 'start_rx' not described in 'uart_ops'
Reviewed-by: Jiri Slaby <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> include/linux/serial_core.h | 8 ++++++++
> 1 file changed, 8 insertions(+)
>
> diff --git a/include/linux/serial_core.h b/include/linux/serial_core.h
> index aef3145f2032..6e4f4765d209 100644
> --- a/include/linux/serial_core.h
> +++ b/include/linux/serial_core.h
> @@ -141,6 +141,14 @@ struct gpio_desc;
> * Locking: none.
> * Interrupts: caller dependent.
> *
> + * @start_rx: ``void ()(struct uart_port *port)``
> + *
> + * Start receiving characters.
> + *
> + * Locking: @port->lock taken.
> + * Interrupts: locally disabled.
> + * This call must not sleep
> + *
> * @stop_rx: ``void ()(struct uart_port *port)``
> *
> * Stop receiving characters; the @port is in the process of being closed.
thanks,
--
js
suse labs
在 2022/8/18 21:38, Mauro Carvalho Chehab 写道:
> There is a note on this file that, using a robot to translate,
> says:
>
> "The kernel-doc cannot contain Rust code: please refer
> to Documentation/rust/general-information.rst."
>
> Such note doesn't exist at the original file anymore, so, just remove
> it from the translation, in order to solve this warning:
>
> Warning: Documentation/translations/zh_CN/doc-guide/kernel-doc.rst references a file that doesn't exist: Documentation/rust/general-information.rst
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Yanteng Si<[email protected]>
Thanks,
Yanteng
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 2 --
> 1 file changed, 2 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> index ccfb9b8329c2..9fd170faf951 100644
> --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> @@ -14,8 +14,6 @@ Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用
> 实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循
> 此处描述的风格。
>
> -.. note:: kernel-doc无法包含Rust代码：请参考 Documentation/rust/general-information.rst 。
> -
> 从注释中提取kernel-doc结构，并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的
> 类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。
>
On 18/08/2022 14:38, Mauro Carvalho Chehab wrote:
> Changeset 66d052047ca8 ("dt-bindings: arm: Convert CoreSight CPU debug to DT schema")
> renamed: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
> to: Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml.
>
> Update its cross-reference accordingly.
>
> Fixes: 66d052047ca8 ("dt-bindings: arm: Convert CoreSight CPU debug to DT schema")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Suzuki K Poulose <[email protected]>
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/trace/coresight/coresight-cpu-debug.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/trace/coresight/coresight-cpu-debug.rst b/Documentation/trace/coresight/coresight-cpu-debug.rst
> index 993dd294b81b..79bbe587e5e8 100644
> --- a/Documentation/trace/coresight/coresight-cpu-debug.rst
> +++ b/Documentation/trace/coresight/coresight-cpu-debug.rst
> @@ -117,7 +117,7 @@ divide into below cases:
> Device Tree Bindings
> --------------------
>
> -See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details.
> +See Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml for details.
>
>
> How to use the module
On 18/08/2022 14:38, Mauro Carvalho Chehab wrote:
> Using wildcards for cross-reference doesn't work, as the Sphinx
> automarkup plugin is not smart enough. So, changeset
> c06475910b52 ("Documentation: coresight: Escape coresight bindings file wildcard")
> tried to fix it, but at the wrong way, as it the building system
> will keep producing warnings about that:
>
> Warning: Documentation/trace/coresight/coresight.rst references a file that doesn't exist: Documentation/devicetree/bindings/arm/arm,coresight-
>
> As automarkup will still try (and fail) to create a cross reference.
> So, instead, change the markup to ensure that the warning won't be
> reported.
>
> Fixes: c06475910b52 ("Documentation: coresight: Escape coresight bindings file wildcard")
> Cc: Bagas Sanjaya <[email protected]>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Suzuki K Poulose <[email protected]>
> ---
>
> See [PATCH 00/13] at: https://lore.kernel.org/all/[email protected]/
>
> Documentation/trace/coresight/coresight.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 4a71ea6cb390..826e59a698da 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -130,7 +130,7 @@ Misc:
> Device Tree Bindings
> --------------------
>
> -See Documentation/devicetree/bindings/arm/arm,coresight-\*.yaml for details.
> +See ``Documentation/devicetree/bindings/arm/arm,coresight-*.yaml`` for details.
>
> As of this writing drivers for ITM, STMs and CTIs are not provided but are
> expected to be added as the solution matures.