Message ID | 20220711171439.1657280-6-trini@konsulko.com |
---|---|
State | Superseded |
Delegated to: | Heinrich Schuchardt |
Headers | show |
Series | [1/7] doc: Migrate CodingStyle wiki page to Sphinx | expand |
On 7/11/22 19:14, Tom Rini wrote: > - Use gender-neutral language to refer to the user, consistently. > - Reword a few places so that they read more naturally. > - Make the long standing practice around "Twilight Time" more clear, > hopefully. > - Replace a reference to MAKEALL with a reference to CI testing as > that's the current requirement. > > Cc: Claudius Heine <ch@denx.de> > Cc: Martin Bonner <martingreybeard@gmail.com> > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > Signed-off-by: Tom Rini <trini@konsulko.com> > --- > Changes in v2: > - Further tweak the wording, per Martin > --- > doc/develop/process.rst | 33 +++++++++++++++++---------------- > 1 file changed, 17 insertions(+), 16 deletions(-) > > diff --git a/doc/develop/process.rst b/doc/develop/process.rst > index 534da4a2a704..d0c46b58f3e9 100644 > --- a/doc/develop/process.rst > +++ b/doc/develop/process.rst > @@ -46,21 +46,22 @@ Twilight Time > ------------- > > Usually patches do not get accepted as they are - the peer review that takes > -place will usually require changes and resubmits of the patches before they > +place will usually require changes and resubmissions of the patches before they > are considered to be ripe for inclusion into mainline. > > -Also, the review often happens not immediately after a patch was submitted, > +Also the review often happens not immediately after a patch was submitted, > but only when somebody (usually the responsible custodian) finds time to do > this. > > -In the result, the final version of such patches gets submitted after the > +The result is that the final version of such patches gets submitted after the > merge window has been closed. > > It is current practice in U-Boot that such patches are eligible to go into the > upcoming release. > > -In the result, the release of the ``"-rc1"`` version does not immediately follow > -the closing of the Merge Window. > +The result is that the release of the ``"-rc1"`` version and formal closing of > +the Merge Window does not preclude patches that were already posted from being > +merged for the upcoming release. > > Stabilization Period > -------------------- > @@ -75,13 +76,13 @@ Sometimes it is not clear if a patch contains a bug fix or not. > For example, changes that remove dead code, unused macros etc. or > that contain Coding Style fixes are not strict bug fixes. > > -In such situations it is up to the responsible custodian to decide if he > -applies such patches even when the Merge Window is closed. > +In such situations it is up to the responsible custodian to decide if they The custodian is singular. > +apply such patches even when the Merge Window is closed. > > Exception: at the end of the Stabilization Period only strict bug > fixes my be applied. > > -Sometimes patches miss the the Merge Window slightly - say by few > +Sometimes patches miss the Merge Window slightly - say by a few > hours or even a day. Patch acceptance is not as critical as a > financial transaction, or such. So if there is such a slight delay, > the custodian is free to turn a blind eye and accept it anyway. The > @@ -110,7 +111,7 @@ Custodians > ---------- > > The Custodians take responsibility for some area of the U-Boot code. The > -in-tree ``MAINTAINERS`` files list who is reponsible for which areas. > +in-tree ``MAINTAINERS`` files list who is responsible for which areas. > > It is their responsibility to pick up patches from the mailing list > that fall into their responsibility, and to process these. > @@ -155,7 +156,7 @@ like this: > > #. Applies cleanly to the source tree > > - #. passes a ``MAKEALL`` compile test without creating new warnings > + #. Passes :doc:`ci_testing` as this checks for new warnings and other issues. %s/ci/CI/ > > #. Notes: > > @@ -167,7 +168,7 @@ like this: > > #. This is well documented in :doc:`designprinciples`. > > - #. The custodian decides himself how recent the code must be. It is > + #. The custodian decides themselves how recent the code must be. It is The custodian is singular. > acceptable to request patches against the last officially released > version of U-Boot or newer. Of course a custodian can also accept > patches against older code. > @@ -177,7 +178,7 @@ like this: > > #. The custodian decides to accept or to reject the patch. > > -#. If accepted, the custodian adds the patch to his public git repository and > +#. If accepted, the custodian adds the patch to their public git repository and > notifies the mailing list. This note should include: > > * a short description of the changes > @@ -186,15 +187,15 @@ like this: > > * suggested tests > > - Although the custodian is supposed to perform his own tests > - it is a well-known and accepted fact that he needs help from > + Although the custodian is supposed to perform their own tests ditto > + it is a well-known and accepted fact that they needs help from > other developers who - for example - have access to the required > hardware or tool chains. > The custodian request help for tests and feedback from > specific maintainers and U-Boot users. > > #. Once tests are passed, some agreed time limit expires, the custodian > - requests that the changes in his public git repository be merged into the > - main tree. If necessary, the custodian may have to adapt his changes to > + requests that the changes in their public git repository be merged into the > + main tree. If necessary, the custodian may have to adapt their changes to ditto Best regards Heinrich > allow for a clean merge. > Todo: define a reasonable time limit. 3 weeks?
On Wed, Jul 13, 2022 at 07:43:25PM +0200, Heinrich Schuchardt wrote: > On 7/11/22 19:14, Tom Rini wrote: [snip] > > @@ -155,7 +156,7 @@ like this: > > > > #. Applies cleanly to the source tree > > > > - #. passes a ``MAKEALL`` compile test without creating new warnings > > + #. Passes :doc:`ci_testing` as this checks for new warnings and other issues. > > %s/ci/CI/ No? This is a reference so it renders using the document title.
diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 534da4a2a704..d0c46b58f3e9 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -46,21 +46,22 @@ Twilight Time ------------- Usually patches do not get accepted as they are - the peer review that takes -place will usually require changes and resubmits of the patches before they +place will usually require changes and resubmissions of the patches before they are considered to be ripe for inclusion into mainline. -Also, the review often happens not immediately after a patch was submitted, +Also the review often happens not immediately after a patch was submitted, but only when somebody (usually the responsible custodian) finds time to do this. -In the result, the final version of such patches gets submitted after the +The result is that the final version of such patches gets submitted after the merge window has been closed. It is current practice in U-Boot that such patches are eligible to go into the upcoming release. -In the result, the release of the ``"-rc1"`` version does not immediately follow -the closing of the Merge Window. +The result is that the release of the ``"-rc1"`` version and formal closing of +the Merge Window does not preclude patches that were already posted from being +merged for the upcoming release. Stabilization Period -------------------- @@ -75,13 +76,13 @@ Sometimes it is not clear if a patch contains a bug fix or not. For example, changes that remove dead code, unused macros etc. or that contain Coding Style fixes are not strict bug fixes. -In such situations it is up to the responsible custodian to decide if he -applies such patches even when the Merge Window is closed. +In such situations it is up to the responsible custodian to decide if they +apply such patches even when the Merge Window is closed. Exception: at the end of the Stabilization Period only strict bug fixes my be applied. -Sometimes patches miss the the Merge Window slightly - say by few +Sometimes patches miss the Merge Window slightly - say by a few hours or even a day. Patch acceptance is not as critical as a financial transaction, or such. So if there is such a slight delay, the custodian is free to turn a blind eye and accept it anyway. The @@ -110,7 +111,7 @@ Custodians ---------- The Custodians take responsibility for some area of the U-Boot code. The -in-tree ``MAINTAINERS`` files list who is reponsible for which areas. +in-tree ``MAINTAINERS`` files list who is responsible for which areas. It is their responsibility to pick up patches from the mailing list that fall into their responsibility, and to process these. @@ -155,7 +156,7 @@ like this: #. Applies cleanly to the source tree - #. passes a ``MAKEALL`` compile test without creating new warnings + #. Passes :doc:`ci_testing` as this checks for new warnings and other issues. #. Notes: @@ -167,7 +168,7 @@ like this: #. This is well documented in :doc:`designprinciples`. - #. The custodian decides himself how recent the code must be. It is + #. The custodian decides themselves how recent the code must be. It is acceptable to request patches against the last officially released version of U-Boot or newer. Of course a custodian can also accept patches against older code. @@ -177,7 +178,7 @@ like this: #. The custodian decides to accept or to reject the patch. -#. If accepted, the custodian adds the patch to his public git repository and +#. If accepted, the custodian adds the patch to their public git repository and notifies the mailing list. This note should include: * a short description of the changes @@ -186,15 +187,15 @@ like this: * suggested tests - Although the custodian is supposed to perform his own tests - it is a well-known and accepted fact that he needs help from + Although the custodian is supposed to perform their own tests + it is a well-known and accepted fact that they needs help from other developers who - for example - have access to the required hardware or tool chains. The custodian request help for tests and feedback from specific maintainers and U-Boot users. #. Once tests are passed, some agreed time limit expires, the custodian - requests that the changes in his public git repository be merged into the - main tree. If necessary, the custodian may have to adapt his changes to + requests that the changes in their public git repository be merged into the + main tree. If necessary, the custodian may have to adapt their changes to allow for a clean merge. Todo: define a reasonable time limit. 3 weeks?
- Use gender-neutral language to refer to the user, consistently. - Reword a few places so that they read more naturally. - Make the long standing practice around "Twilight Time" more clear, hopefully. - Replace a reference to MAKEALL with a reference to CI testing as that's the current requirement. Cc: Claudius Heine <ch@denx.de> Cc: Martin Bonner <martingreybeard@gmail.com> Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> Signed-off-by: Tom Rini <trini@konsulko.com> --- Changes in v2: - Further tweak the wording, per Martin --- doc/develop/process.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-)