doc: add dependency syntax to contributing guide
diff mbox series

Message ID 20200701113528.303605-1-ferruh.yigit@intel.com
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • doc: add dependency syntax to contributing guide
Related show

Checks

Context Check Description
ci/Intel-compilation success Compilation OK
ci/travis-robot success Travis build: errored
ci/checkpatch success coding style OK

Commit Message

Ferruh Yigit July 1, 2020, 11:35 a.m. UTC
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'

Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
---
Cc: ci@dpdk.org
---
 doc/guides/contributing/patches.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

Comments

Thomas Monjalon July 1, 2020, 11:59 a.m. UTC | #1
01/07/2020 13:35, 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' 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")
Ferruh Yigit July 2, 2020, 4:13 p.m. UTC | #2
On 7/1/2020 12:59 PM, Thomas Monjalon wrote:
> 01/07/2020 13:35, 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' 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?
Thomas Monjalon July 3, 2020, 9:01 a.m. UTC | #3
02/07/2020 18:13, Ferruh Yigit:
> On 7/1/2020 12:59 PM, Thomas Monjalon wrote:
> > 01/07/2020 13:35, 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' 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?

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.
Ferruh Yigit July 3, 2020, 9:03 a.m. UTC | #4
On 7/3/2020 10:01 AM, Thomas Monjalon wrote:
> 02/07/2020 18:13, Ferruh Yigit:
>> On 7/1/2020 12:59 PM, Thomas Monjalon wrote:
>>> 01/07/2020 13:35, 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' 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?
> 
> It should be in cover letter if there is one.
> If no cover letter, I would prefer not having it in git,

+1

> so I would suggest having a line of --- before.

OK

Patch
diff mbox series

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index 1c6a04100..54dbb0508 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -339,6 +339,27 @@  In the commit message body the Cc: stable@dpdk.org 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 <alex.smith@example.com>
+     ---
+     Depends-on: series-10000
 
 Creating Patches
 ----------------