Skip to contentSkip to conversation

doc: add dependency syntax to contributing guide

PATCH Superseded Ferruh Yigit 3 participants 10 messages Jul 1, 2020 – Jul 30, 2020

lore
Share & tools
lore
#0 lore raw

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
index 1c6a04100..54dbb0508 100644
@@ -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
#1 lore raw

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")

#2 lore raw
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?

#3 lore raw

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.

#4 lore raw
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

#5 lore raw

PATCH v2 1/1 doc: add dependency syntax to contributing guide

In reply to 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]

"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
index 16b40225f..73f71fc69 100644
@@ -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
#6 lore raw
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")'

---

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
index 16b40225f..73f71fc69 100644
@@ -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

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
 ----------------
#7 lore raw

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")'

---

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.

#8 lore raw
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")'

---

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.

Acked-by on v2 1/1 Applied
#9 lore raw
In reply to Ferruh Yigit

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")'

Applied, thanks