doc: add dependency syntax to contributing guide
PATCH 1/1 doc: add dependency syntax to contributing guide
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]
'Depends-on: series-NNNNN' OR 'Depends-on: patch-NNNNN'
---
Cc: [email protected]
--- doc/guides/contributing/patches.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
doc/guides/contributing/patches.rst +21 -0
@@ -339,6 +339,27 @@ In the commit message body the Cc: [email protected] should be inserted as follows For further information on stable contribution you can go to :doc:`Stable Contribution Guide <stable>`. +Patch Dependencies +~~~~~~~~~~~~~~~~~~ + +Sometimes a patch or patchset can depend on another one. +To help the maintainers and automation tasks, please document this dependency in commit log or cover letter with the following syntax:: + + Depends-on: series-NNNNN + + OR + + Depends-on: patch-NNNNN + +Where ``NNNNN`` is patchwork ID for patch or series:: + + doc: fix some parameter description + + Update the docs, fixing description of some parameter. + + Signed-off-by: Alex Smith <[email protected]> + --- + Depends-on: series-10000 Creating Patches ----------------
Signature · 1 line
2.25.4
01/07/2020 13:35, Ferruh Yigit:
Quoted 8 lines
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]'Depends-on: series-NNNNN' OR 'Depends-on: patch-NNNNN'
It would be more convenient to add the patch or series title as we do for "Fixes" tag:
Depends-on: series-NNNNN ("Title of the series")
Quoted 8 lines · Thomas Monjalon
01/07/2020 13:35, Ferruh Yigit:
Quoted 7 lines
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]
Quoted 6 lines
Quoted 1 line
'Depends-on: series-NNNNN' OR 'Depends-on: patch-NNNNN'
It would be more convenient to add the patch or series title as we do for "Fixes" tag:
Depends-on: series-NNNNN ("Title of the series")
OK, will update in next version.
Should we enforce any location for the tag, like first of line of the commit log or cover letter? Does something like this helps to parsers?
02/07/2020 18:13, Ferruh Yigit:
Quoted 14 lines · Thomas Monjalon
Quoted 13 lines
01/07/2020 13:35, Ferruh Yigit:
Quoted 8 lines
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]'Depends-on: series-NNNNN' OR 'Depends-on: patch-NNNNN'
It would be more convenient to add the patch or series title as we do for "Fixes" tag:
Quoted 6 lines
Quoted 1 line
Depends-on: series-NNNNN ("Title of the series")
OK, will update in next version.
Should we enforce any location for the tag, like first of line of the commit log or cover letter? Does something like this helps to parsers?
It should be in cover letter if there is one. If no cover letter, I would prefer not having it in git, so I would suggest having a line of --- before.
Quoted 17 lines · Thomas Monjalon
02/07/2020 18:13, Ferruh Yigit:
Quoted 16 lines · Thomas Monjalon
Quoted 14 lines
01/07/2020 13:35, Ferruh Yigit:
Quoted 8 lines
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]'Depends-on: series-NNNNN' OR 'Depends-on: patch-NNNNN'
It would be more convenient to add the patch or series title as we do for "Fixes" tag:
Depends-on: series-NNNNN ("Title of the series")
Quoted 7 lines
Quoted 4 lines
OK, will update in next version.
Should we enforce any location for the tag, like first of line of the commit log or cover letter? Does something like this helps to parsers?
It should be in cover letter if there is one. If no cover letter, I would prefer not having it in git,
+1
Quoted 1 line
so I would suggest having a line of --- before.
OK
PATCH v2 1/1 doc: add dependency syntax to contributing guide
In reply to Ferruh YigitTo help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]
"Depends-on: series-NNNNN ("Title of the series")' OR
'Depends-on: patch-NNNNN ("Title of the patch")'
---
Cc: [email protected]
v2:
* Add patch/series title as part of syntax
--- doc/guides/contributing/patches.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)
doc/guides/contributing/patches.rst +18 -0
@@ -336,6 +336,24 @@ In the commit message body the Cc: [email protected] should be inserted as follows For further information on stable contribution you can go to :doc:`Stable Contribution Guide <stable>`. +Patch Dependencies +~~~~~~~~~~~~~~~~~~ + +Sometimes a patch or patchset can depend on another one. +To help the maintainers and automation tasks, please document this dependency in commit log or cover letter +with the following syntax: + +``Depends-on: series-NNNNN ("Title of the series")`` or ``Depends-on: patch-NNNNN ("Title of the patch")`` + +Where ``NNNNN`` is patchwork ID for patch or series:: + + doc: fix some parameter description + + Update the docs, fixing description of some parameter. + + Signed-off-by: Alex Smith <[email protected]> + --- + Depends-on: series-10000 ("Title of the series") Creating Patches ----------------
Signature · 1 line
2.25.4
Quoted 7 lines · Ferruh Yigit
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]
Quoted 6 lines
"Depends-on: series-NNNNN ("Title of the series")' OR
'Depends-on: patch-NNNNN ("Title of the patch")'Signed-off-by Ferruh Yigit <[email protected]>---
Is the plan that these must be scrubbed before committing?
This data doesn't seem useful in the history. I would prefer it in the subject like
[PATCH series-xxxx] lorem ipsum
Since the metadata gets scrubbed.
Quoted 38 lines
v2:
* Add patch/series title as part of syntax--- doc/guides/contributing/patches.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)doc/guides/contributing/patches.rst +5
-0@@ -336,6 +336,24 @@ In the commit message body the Cc: [email protected] should be inserted as follows For further information on stable contribution you can go to :doc:`Stable Contribution Guide <stable>`. +Patch Dependencies +~~~~~~~~~~~~~~~~~~ + +Sometimes a patch or patchset can depend on another one. +To help the maintainers and automation tasks, please document thisdependency in commit log or cover letter
doc/guides/contributing/patches.rst +13
-0+with the following syntax: + +``Depends-on: series-NNNNN ("Title of the series")`` or ``Depends-on: patch-NNNNN ("Title of the patch")`` + +Where ``NNNNN`` is patchwork ID for patch or series:: + + doc: fix some parameter description + + Update the docs, fixing description of some parameter. + + Signed-off-by: Alex Smith <[email protected]> + --- + Depends-on: series-10000 ("Title of the series") Creating Patches ----------------
06/07/2020 17:09, Aaron Conole:
Quoted 16 lines
Quoted 7 lines · Ferruh Yigit
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]Quoted 6 lines
"Depends-on: series-NNNNN ("Title of the series")' OR
'Depends-on: patch-NNNNN ("Title of the patch")'Signed-off-by Ferruh Yigit <[email protected]>---
Quoted 8 lines
Is the plan that these must be scrubbed before committing?
This data doesn't seem useful in the history. I would prefer it in the subject like
[PATCH series-xxxx] lorem ipsum
Since the metadata gets scrubbed.
Look below:
Quoted 3 lines
doc/guides/contributing/patches.rst In the commit message body the Cc: [email protected] should be inserted as follows · line 356
Quoted 3 lines
doc/guides/contributing/patches.rst +3
-0+ Signed-off-by: Alex Smith <[email protected]> + --- + Depends-on: series-10000 ("Title of the series")
Added after line ---
so it won't be kept in the git history.
Quoted 26 lines · Thomas Monjalon
06/07/2020 17:09, Aaron Conole:
Quoted 16 lines
Quoted 7 lines · Ferruh Yigit
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]Quoted 6 lines
"Depends-on: series-NNNNN ("Title of the series")' OR
'Depends-on: patch-NNNNN ("Title of the patch")'Signed-off-by Ferruh Yigit <[email protected]>---
Quoted 8 lines
Is the plan that these must be scrubbed before committing?
This data doesn't seem useful in the history. I would prefer it in the subject like
[PATCH series-xxxx] lorem ipsum
Since the metadata gets scrubbed.
Quoted 8 lines
Look below:
Quoted 3 lines
doc/guides/contributing/patches.rst In the commit message body the Cc: [email protected] should be inserted as follows · line 356
Quoted 3 lines
doc/guides/contributing/patches.rst +3
-0+ Signed-off-by: Alex Smith <[email protected]> + --- + Depends-on: series-10000 ("Title of the series")Added after line ---
so it won't be kept in the git history.
Ahh, I missed it for some reason.
03/07/2020 11:53, Ferruh Yigit:
Quoted 4 lines
To help managing patch dependencies, both for maintainers or automation tasks, document a syntax for commit logs or cover letters to express their dependencies.
Quoted 8 lines
Using the syntax proposed in Bugzilla ID 210:
[https://bugs.dpdk.org/show_bug.cgi?id=210]"Depends-on: series-NNNNN ("Title of the series")' OR
'Depends-on: patch-NNNNN ("Title of the patch")'Signed-off-by Ferruh Yigit <[email protected]>
Applied, thanks