[v6] doc: add release milestones definition

  From: Asaf Penso <asafp@nvidia.com>

Adding more information about the release milestones.
This includes the scope of change, expectations, etc.

Signed-off-by: Asaf Penso <asafp@nvidia.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: John McNamara <john.mcnamara@intel.com>
---
v2: fix styling format and add content in the commit message
v3: change punctuation and avoid plural form when unneeded
v4: avoid abbreviations, "Priority" in -rc, and reword as John suggests
v5: note that release candidates may vary
v6: merge RFC and proposal deadline, add roadmap link and reduce duplication
---
 doc/guides/contributing/patches.rst | 69 +++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
  

On Sun, Mar 28, 2021 at 12:00 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> From: Asaf Penso <asafp@nvidia.com>
>
> Adding more information about the release milestones.
> This includes the scope of change, expectations, etc.
>
> Signed-off-by: Asaf Penso <asafp@nvidia.com>
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: Ajit Khaparde <ajit.khaparde@broadcom.com>

> ---
> v2: fix styling format and add content in the commit message
> v3: change punctuation and avoid plural form when unneeded
> v4: avoid abbreviations, "Priority" in -rc, and reword as John suggests
> v5: note that release candidates may vary
> v6: merge RFC and proposal deadline, add roadmap link and reduce duplication
> ---
>  doc/guides/contributing/patches.rst | 69 +++++++++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
>
> diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
> index 6dbbd5f8d1..1277443620 100644
> --- a/doc/guides/contributing/patches.rst
> +++ b/doc/guides/contributing/patches.rst
> @@ -177,6 +177,8 @@ Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines
>  * Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.
>    See the :ref:`Documentation Guidelines <doc_guidelines>`.
>
> +* Code and related documentation must be updated atomically in the same patch.
> +
>  Once the changes have been made you should commit them to your local repo.
>
>  For small changes, that do not require specific explanations, it is better to keep things together in the
> @@ -660,3 +662,70 @@ patch accepted. The general cycle for patch review and acceptance is:
>       than rework of the original.
>     * Trivial patches may be merged sooner than described above at the tree committer's
>       discretion.
> +
> +
> +Milestones definition
> +---------------------
> +
> +Each DPDK release has milestones that help everyone to converge to the release date.
> +The following is a list of these milestones
> +together with concrete definitions and expectations,
> +for a typical release cycle (3 months ending after 4 release candidates).
> +The number and expectations of release candidates might vary slightly.
> +The schedule is updated in the `roadmap <https://core.dpdk.org/roadmap/#dates>`_.
> +
> +Roadmap
> +~~~~~~~
> +
> +* Announce new features in libraries, drivers, applications, and examples.
> +* To be published before the first day of the release cycle.
> +
> +Proposal Deadline
> +~~~~~~~~~~~~~~~~~
> +
> +* Must send an RFC or a complete v1 patch.
> +* Early RFC gives time for design review before complete implementation.
> +* Should include at least the API changes in libraries and applications.
> +* Library code should be quite complete at the deadline.
> +* Nice to have: driver implementation (full or draft), example code, and documentation.
> +
> +rc1
> +~~~
> +
> +* Priority: new or updated API.
> +* New API should be defined and implemented in libraries.
> +* The API should include Doxygen documentation
> +  and be part of the relevant .rst files (library-specific and release notes).
> +* API should be used in a test application (``/app``).
> +* At least one PMD should implement the API.
> +  It can be a draft but must be sent as a separate series.
> +* The above should be sent to the mailing list at least 2 weeks before -rc1.
> +* Nice to have: example code (``/examples``)
> +
> +rc2
> +~~~
> +
> +* Priority: drivers.
> +* New features should be implemented in drivers.
> +* A driver change should include documentation
> +  in the relevant .rst files (driver-specific and release notes).
> +* The above should be sent to the mailing list at least 2 weeks before -rc2.
> +
> +rc3
> +~~~
> +
> +* Priority: applications.
> +* New functionality that does not depend on libraries update
> +  can be integrated as part of -rc3.
> +* The application should include documentation in the relevant .rst files
> +  (application-specific and release notes if significant).
> +* It may be the last opportunity for miscellaneous changes.
> +* Libraries and drivers cleanup are allowed.
> +* Small driver reworks.
> +* Critical and minor bug fixes.
> +
> +rc4
> +~~~
> +
> +* Documentation updates.
> +* Critical bug fixes.
> --
> 2.30.1
>
  

On 3/28/2021 8:00 PM, Thomas Monjalon wrote:
> From: Asaf Penso <asafp@nvidia.com>
> 
> Adding more information about the release milestones.
> This includes the scope of change, expectations, etc.
> 
> Signed-off-by: Asaf Penso <asafp@nvidia.com>
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> Acked-by: John McNamara <john.mcnamara@intel.com>
> ---
> v2: fix styling format and add content in the commit message
> v3: change punctuation and avoid plural form when unneeded
> v4: avoid abbreviations, "Priority" in -rc, and reword as John suggests
> v5: note that release candidates may vary
> v6: merge RFC and proposal deadline, add roadmap link and reduce duplication
> ---
>  doc/guides/contributing/patches.rst | 69 +++++++++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
> 
> diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
> index 6dbbd5f8d1..1277443620 100644
> --- a/doc/guides/contributing/patches.rst
> +++ b/doc/guides/contributing/patches.rst
> @@ -177,6 +177,8 @@ Make your planned changes in the cloned ``dpdk`` repo. Here are some guidelines
>  * Add documentation, if relevant, in the form of Doxygen comments or a User Guide in RST format.
>    See the :ref:`Documentation Guidelines <doc_guidelines>`.
>  
> +* Code and related documentation must be updated atomically in the same patch.
> +
>  Once the changes have been made you should commit them to your local repo.
>  
>  For small changes, that do not require specific explanations, it is better to keep things together in the
> @@ -660,3 +662,70 @@ patch accepted. The general cycle for patch review and acceptance is:
>       than rework of the original.
>     * Trivial patches may be merged sooner than described above at the tree committer's
>       discretion.
> +
> +
> +Milestones definition
> +---------------------
> +
> +Each DPDK release has milestones that help everyone to converge to the release date.
> +The following is a list of these milestones
> +together with concrete definitions and expectations,
> +for a typical release cycle (3 months ending after 4 release candidates).
> +The number and expectations of release candidates might vary slightly.
> +The schedule is updated in the `roadmap <https://core.dpdk.org/roadmap/#dates>`_.
> +
> +Roadmap
> +~~~~~~~
> +
> +* Announce new features in libraries, drivers, applications, and examples.
> +* To be published before the first day of the release cycle.
> +
> +Proposal Deadline
> +~~~~~~~~~~~~~~~~~
> +
> +* Must send an RFC or a complete v1 patch.
> +* Early RFC gives time for design review before complete implementation.
> +* Should include at least the API changes in libraries and applications.
> +* Library code should be quite complete at the deadline.
> +* Nice to have: driver implementation (full or draft), example code, and documentation.
> +
> +rc1
> +~~~
> +
> +* Priority: new or updated API.

Can we just say API or libraries?

Overall what is the intention for the 'priority' information? Should we really
split release candidates for libraries, driver and applications?
We merge all as much as possible before -rc1.

Can we say this other-way around, API/library features can't be merged after -rc1.

And similarly driver features shouldn't be merged after -rc2, application
changes shouldn't merge after -rc3.
Fixes can be merged anytime before -rc4. After -rc4 only critical fixes and
documentation changes.

Just I want to highlight that for example we merge documentation updates
anytime, it doesn't have to wait -rc4, but below listing looks like different
part only allocated for different -rc, which is wrong as far as I know.

> +* New API should be defined and implemented in libraries.> +* The API should include Doxygen documentation

s/should/must

> +  and be part of the relevant .rst files (library-specific and release notes).
> +* API should be used in a test application (``/app``).
> +* At least one PMD should implement the API.
> +  It can be a draft but must be sent as a separate series.

I am not sure if "must be sent as a separate series" needs to be highlighted,
having all in the same series has a benefit to see bigger picture. If the driver
patches acked/reviewed by its maintainers, I think it can be merged in single
series.

> +* The above should be sent to the mailing list at least 2 weeks before -rc1.
> +* Nice to have: example code (``/examples``)
> +
> +rc2
> +~~~
> +
> +* Priority: drivers.
> +* New features should be implemented in drivers.

I already mentioned above, but this can cause misunderstanding. We want all
driver implementation to be ready for proposal deadline, same as other patches.
But because of its reduced scope (they don't affect all project but only
specific vendor), we are flexible to get driver features for -rc2 and -rc3 too.

Please check number of driver patches merged for a release, it is impossible to
manage them within period between -rc1 & -rc2.
Also some driver features are complex and big, they should be sent before
proposal deadline so that they can be reviewed for the release.

> +* A driver change should include documentation

s/should/must

> +  in the relevant .rst files (driver-specific and release notes).
> +* The above should be sent to the mailing list at least 2 weeks before -rc2.
> +
> +rc3
> +~~~
> +
> +* Priority: applications.
> +* New functionality that does not depend on libraries update
> +  can be integrated as part of -rc3.

Again for same issue, let me share my understanding,
the -rc1 has been tested widely, after that each -rc gets less and less tests.
So the -rc1 should have API/library changes, so that they will be tested more
and will have more time to fix any issues, since library changes has biggest
impact for the project.

Next biggest impact is drivers.

Applications and unit tests are internal to DPDK, they have no user impact, that
is why we can get more risk with them and they can be merged even as late as rc3.

And documentation doesn't have anything related to testing, or they don't
introduce any risk for specific release, so they are merged until last stage of
the release.

> +* The application should include documentation in the relevant .rst files
> +  (application-specific and release notes if significant).

s/should/must

> +* It may be the last opportunity for miscellaneous changes.

This is very vague, what does misch changes mean?

> +* Libraries and drivers cleanup are allowed.
> +* Small driver reworks.
> +* Critical and minor bug fixes.
> +
> +rc4
> +~~~
> +
> +* Documentation updates.
> +* Critical bug fixes.
>
  

18/05/2021 13:57, Ferruh Yigit:
> On 3/28/2021 8:00 PM, Thomas Monjalon wrote:
> > From: Asaf Penso <asafp@nvidia.com>
> > 
> > Adding more information about the release milestones.
> > This includes the scope of change, expectations, etc.
[...]
> > +rc1
> > +~~~
> > +
> > +* Priority: new or updated API.
> 
> Can we just say API or libraries?

Yes

> Overall what is the intention for the 'priority' information? Should we really
> split release candidates for libraries, driver and applications?
> We merge all as much as possible before -rc1.

The idea is to simply reflect the priority
in case time is limited. But yes we always merge as much as possible.

> Can we say this other-way around, API/library features can't be merged after -rc1.

Correct

> And similarly driver features shouldn't be merged after -rc2, application
> changes shouldn't merge after -rc3.
> Fixes can be merged anytime before -rc4. After -rc4 only critical fixes and
> documentation changes.
> 
> Just I want to highlight that for example we merge documentation updates
> anytime, it doesn't have to wait -rc4, but below listing looks like different
> part only allocated for different -rc, which is wrong as far as I know.

I understand the confusion and will try to make it clearer in next revision.

> > +* New API should be defined and implemented in libraries.
> > +* The API should include Doxygen documentation
> 
> s/should/must

OK

> > +  and be part of the relevant .rst files (library-specific and release notes).
> > +* API should be used in a test application (``/app``).
> > +* At least one PMD should implement the API.
> > +  It can be a draft but must be sent as a separate series.
> 
> I am not sure if "must be sent as a separate series" needs to be highlighted,
> having all in the same series has a benefit to see bigger picture. If the driver
> patches acked/reviewed by its maintainers, I think it can be merged in single
> series.

That's not the same kind of review for driver and API,
not the same time constraint, and not the same iterations.
I think it is more practical to suggest separate,
but it should not be "must".

> > +* The above should be sent to the mailing list at least 2 weeks before -rc1.
> > +* Nice to have: example code (``/examples``)
> > +
> > +rc2
> > +~~~
> > +
> > +* Priority: drivers.
> > +* New features should be implemented in drivers.
> 
> I already mentioned above, but this can cause misunderstanding. We want all
> driver implementation to be ready for proposal deadline, same as other patches.
> But because of its reduced scope (they don't affect all project but only
> specific vendor), we are flexible to get driver features for -rc2 and -rc3 too.

-rc3 really? It should be exceptional so not mentioned here.

> Please check number of driver patches merged for a release, it is impossible to
> manage them within period between -rc1 & -rc2.
> Also some driver features are complex and big, they should be sent before
> proposal deadline so that they can be reviewed for the release.

Yes sooner is better. The doc is about deadline + priorities,
showing the no-go limits, without warranty of merge if all good.
Is there a contradiction?

> > +* A driver change should include documentation
> 
> s/should/must

Sometimes there is no doc to change. Is "must" confusing?

> > +  in the relevant .rst files (driver-specific and release notes).
> > +* The above should be sent to the mailing list at least 2 weeks before -rc2.
> > +
> > +rc3
> > +~~~
> > +
> > +* Priority: applications.
> > +* New functionality that does not depend on libraries update
> > +  can be integrated as part of -rc3.
> 
> Again for same issue, let me share my understanding,
> the -rc1 has been tested widely, after that each -rc gets less and less tests.
> So the -rc1 should have API/library changes, so that they will be tested more
> and will have more time to fix any issues, since library changes has biggest
> impact for the project.
> 
> Next biggest impact is drivers.
> 
> Applications and unit tests are internal to DPDK, they have no user impact, that
> is why we can get more risk with them and they can be merged even as late as rc3.
> 
> And documentation doesn't have anything related to testing, or they don't
> introduce any risk for specific release, so they are merged until last stage of
> the release.

Yes

> > +* The application should include documentation in the relevant .rst files
> > +  (application-specific and release notes if significant).
> 
> s/should/must
> 
> > +* It may be the last opportunity for miscellaneous changes.
> 
> This is very vague, what does misch changes mean?

Scripts, code cleanup, yes it is vague, we can remove.

> > +* Libraries and drivers cleanup are allowed.
> > +* Small driver reworks.
> > +* Critical and minor bug fixes.
> > +
> > +rc4
> > +~~~
> > +
> > +* Documentation updates.
> > +* Critical bug fixes.
  

On 5/18/2021 1:25 PM, Thomas Monjalon wrote:
> 18/05/2021 13:57, Ferruh Yigit:
>> On 3/28/2021 8:00 PM, Thomas Monjalon wrote:
>>> From: Asaf Penso <asafp@nvidia.com>
>>>
>>> Adding more information about the release milestones.
>>> This includes the scope of change, expectations, etc.
> [...]
>>> +rc1
>>> +~~~
>>> +
>>> +* Priority: new or updated API.
>>
>> Can we just say API or libraries?
> 
> Yes
> 
>> Overall what is the intention for the 'priority' information? Should we really
>> split release candidates for libraries, driver and applications?
>> We merge all as much as possible before -rc1.
> 
> The idea is to simply reflect the priority
> in case time is limited. But yes we always merge as much as possible.
> 
>> Can we say this other-way around, API/library features can't be merged after -rc1.
> 
> Correct
> 
>> And similarly driver features shouldn't be merged after -rc2, application
>> changes shouldn't merge after -rc3.
>> Fixes can be merged anytime before -rc4. After -rc4 only critical fixes and
>> documentation changes.
>>
>> Just I want to highlight that for example we merge documentation updates
>> anytime, it doesn't have to wait -rc4, but below listing looks like different
>> part only allocated for different -rc, which is wrong as far as I know.
> 
> I understand the confusion and will try to make it clearer in next revision.
> 
>>> +* New API should be defined and implemented in libraries.
>>> +* The API should include Doxygen documentation
>>
>> s/should/must
> 
> OK
> 
>>> +  and be part of the relevant .rst files (library-specific and release notes).
>>> +* API should be used in a test application (``/app``).
>>> +* At least one PMD should implement the API.
>>> +  It can be a draft but must be sent as a separate series.
>>
>> I am not sure if "must be sent as a separate series" needs to be highlighted,
>> having all in the same series has a benefit to see bigger picture. If the driver
>> patches acked/reviewed by its maintainers, I think it can be merged in single
>> series.
> 
> That's not the same kind of review for driver and API,
> not the same time constraint, and not the same iterations.
> I think it is more practical to suggest separate,
> but it should not be "must".
> 
>>> +* The above should be sent to the mailing list at least 2 weeks before -rc1.
>>> +* Nice to have: example code (``/examples``)
>>> +
>>> +rc2
>>> +~~~
>>> +
>>> +* Priority: drivers.
>>> +* New features should be implemented in drivers.
>>
>> I already mentioned above, but this can cause misunderstanding. We want all
>> driver implementation to be ready for proposal deadline, same as other patches.
>> But because of its reduced scope (they don't affect all project but only
>> specific vendor), we are flexible to get driver features for -rc2 and -rc3 too.
> 
> -rc3 really? It should be exceptional so not mentioned here.
> 

In practice we are having it, but agree to have it exceptional and not mention
in the guide.

>> Please check number of driver patches merged for a release, it is impossible to
>> manage them within period between -rc1 & -rc2.
>> Also some driver features are complex and big, they should be sent before
>> proposal deadline so that they can be reviewed for the release.
> 
> Yes sooner is better. The doc is about deadline + priorities,
> showing the no-go limits, without warranty of merge if all good.
> Is there a contradiction?
> 

My concern is document can be read as, it is normal/expected to send driver
patches after -rc1, because this documents as -rc2 task is driver patches.

I am OK with it if it is clear that deadline is -rc2, but normal/expected is to
have driver patches also before proposal deadline.

>>> +* A driver change should include documentation
>>
>> s/should/must
> 
> Sometimes there is no doc to change. Is "must" confusing?
> 

I believe we can improve our documentation, there are some new features driver
or library, not documented at all.

But you are right, there may be driver features that may not require any
documentation, but if there is a feature big enough for documentation, I am for
having documentation as a 'must', not sure how to clearly document this.

>>> +  in the relevant .rst files (driver-specific and release notes).
>>> +* The above should be sent to the mailing list at least 2 weeks before -rc2.
>>> +
>>> +rc3
>>> +~~~
>>> +
>>> +* Priority: applications.
>>> +* New functionality that does not depend on libraries update
>>> +  can be integrated as part of -rc3.
>>
>> Again for same issue, let me share my understanding,
>> the -rc1 has been tested widely, after that each -rc gets less and less tests.
>> So the -rc1 should have API/library changes, so that they will be tested more
>> and will have more time to fix any issues, since library changes has biggest
>> impact for the project.
>>
>> Next biggest impact is drivers.
>>
>> Applications and unit tests are internal to DPDK, they have no user impact, that
>> is why we can get more risk with them and they can be merged even as late as rc3.
>>
>> And documentation doesn't have anything related to testing, or they don't
>> introduce any risk for specific release, so they are merged until last stage of
>> the release.
> 
> Yes
> 
>>> +* The application should include documentation in the relevant .rst files
>>> +  (application-specific and release notes if significant).
>>
>> s/should/must
>>
>>> +* It may be the last opportunity for miscellaneous changes.
>>
>> This is very vague, what does misch changes mean?
> 
> Scripts, code cleanup, yes it is vague, we can remove.
> 
>>> +* Libraries and drivers cleanup are allowed.
>>> +* Small driver reworks.
>>> +* Critical and minor bug fixes.
>>> +
>>> +rc4
>>> +~~~
>>> +
>>> +* Documentation updates.
>>> +* Critical bug fixes.
> 
> 
>
  

>
>
> >> I already mentioned above, but this can cause misunderstanding. We want
> all
> >> driver implementation to be ready for proposal deadline, same as other
> patches.
> >> But because of its reduced scope (they don't affect all project but only
> >> specific vendor), we are flexible to get driver features for -rc2 and
> -rc3 too.
> >
> > -rc3 really? It should be exceptional so not mentioned here.
>
Agree. Let's keep it to -rc2.


> >
>
> In practice we are having it, but agree to have it exceptional and not
> mention
> in the guide.
>
> >> Please check number of driver patches merged for a release, it is
> impossible to
> >> manage them within period between -rc1 & -rc2.
> >> Also some driver features are complex and big, they should be sent
> before
> >> proposal deadline so that they can be reviewed for the release.
> >
> > Yes sooner is better. The doc is about deadline + priorities,
> > showing the no-go limits, without warranty of merge if all good.
> > Is there a contradiction?
> >
>
> My concern is document can be read as, it is normal/expected to send driver
> patches after -rc1, because this documents as -rc2 task is driver patches.
>
> I am OK with it if it is clear that deadline is -rc2, but normal/expected
> is to
> have driver patches also before proposal deadline.
>
+1


>
>
>
>