[PATCH 1/2] designprinciples.rst: Perform minor cleanups

[PATCH 1/2] designprinciples.rst: Perform minor cleanups

[Tom Rini]

- Remove some missed wiki markup, and escape a "\n" correctly.
- Use gender-neutral language to refer to the user, consistently.

Cc: Claudius Heine <ch@denx.de>
Signed-off-by: Tom Rini <trini@konsulko.com>
---
 doc/develop/designprinciples.rst | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst
index 79694db77604..b6ceff1aa02b 100644
--- a/doc/develop/designprinciples.rst
+++ b/doc/develop/designprinciples.rst
@@ -18,8 +18,8 @@ relatively small NOR flash memory, which is expensive
 compared to the much larger NAND devices often used to store the
 operating system and the application.
 
-At the moment, U-Boot supports boards with just 128 !KiB ROM or with
-256 !KiB NOR flash. We should not easily ignore such configurations -
+At the moment, U-Boot supports boards with just 128 KiB ROM or with
+256 KiB NOR flash. We should not easily ignore such configurations -
 they may be the exception in among all the other supported boards,
 but if a design uses such a resource-constrained hardware setup it is
 usually because costs are critical, i. e. because the number of
@@ -28,15 +28,15 @@ millions...
 
 A usable and useful configuration of U-Boot, including a basic
 interactive command interpreter, support for download over Ethernet
-and the capability to program the flash shall fit in no more than 128 !KiB.
+and the capability to program the flash shall fit in no more than 128 KiB.
 
 Keep it Fast
 ^^^^^^^^^^^^
 
 The end user is not interested in running U-Boot. In most embedded
-systems he is not even aware that U-Boot exists. The user wants to
+systems they are not even aware that U-Boot exists. The user wants to
 run some application code, and that as soon as possible after switching
-on his device.
+on their device.
 
 It is therefore essential that U-Boot is as fast as possible,
 especially that it loads and boots the operating system as fast as possible.
@@ -62,7 +62,7 @@ Keep it Simple
 ^^^^^^^^^^^^^^
 
 U-Boot is a boot loader, but it is also a tool used for board
-bring-up, for production testing, and for other activities
+bring-up, for production testing, and for other activities.
 
 Keep it Portable
 ^^^^^^^^^^^^^^^^
@@ -95,13 +95,13 @@ Keep it Configurable
 Section "Keep it Small" already explains about the size restrictions
 for U-Boot on one side. On the other side, U-Boot is a powerful tool
 with many, many extremely useful features. The maintainer or user of
-each board will have to decide which features are important to him and
-what shall be included with his specific board configuration to meet
-his current requirements and restrictions.
+each board will have to decide which features are important to them and
+what shall be included with their specific board configuration to meet
+their current requirements and restrictions.
 
 Please make sure that it is easy to add or remove features from a
 board configuration, so everybody can make the best use of U-Boot on
-his system.
+their system.
 
 If a feature is not included, it should not have any residual code
 bloating the build.
@@ -124,7 +124,7 @@ debug is all the more important to many of us.
 * All initialization steps shall print some "begin doing this" message before
   they actually start, and some "done" message when they complete. For example,
   RAM initialization and size detection may print a "RAM: " before they start,
-  and "256 MB\n" when done.  The purpose of this is that you can always see
+  and "256 MB\\n" when done.  The purpose of this is that you can always see
   which initialization step was running if there should be any problem.  This
   is important not only during software development, but also for the service
   people dealing with broken hardware in the field.
@@ -140,8 +140,8 @@ Please always keep in mind that there are at least three different
 groups of users for U-Boot, with completely different expectations
 and requirements:
 
-* The end user of an embedded device just wants to run some application; he
-  does not even want to know that U-Boot exists and only rarely interacts with
+* The end user of an embedded device just wants to run some application; they
+  do not even want to know that U-Boot exists and only rarely interacts with
   it (for example to perform a reset to factory default settings etc.)
 * System designers and engineers working on the development of the application
   and/or the operating system want a powerful tool that can boot from any boot
@@ -151,7 +151,7 @@ and requirements:
   U-Boot to be as simple as possible so porting it to and maintaining it on
   their hardware is easy for them.
 * Make it easy to test. Add debug code (but don't re-invent the wheel - use
-  existing macros like debug() or debugX()).
+  existing macros like debug()).
 
 Please always keep in mind that U-Boot tries to meet all these
 different requirements.
-- 
2.25.1

[PATCH 2/2] process.rst: Perform minor cleanups

[Tom Rini]

- 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>
Signed-off-by: Tom Rini <trini@konsulko.com>
---
 doc/develop/process.rst | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/doc/develop/process.rst b/doc/develop/process.rst
index dd279fb9eff1..8f471fd161b2 100644
--- a/doc/develop/process.rst
+++ b/doc/develop/process.rst
@@ -42,21 +42,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,
 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
 --------------------
@@ -71,13 +72,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 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
@@ -105,7 +106,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.
@@ -144,7 +145,7 @@ like this:
 
    #. U-Boot Philosophy
    #. 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:
 
@@ -153,7 +154,7 @@ like this:
      patch should send a short ACK to the mailing list.
   #. We should create some tool to automatically do 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.
@@ -161,22 +162,22 @@ like this:
       sign off/ack lines.
 
 5. 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
    * the list of the affected boards / architectures etc.
    * 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?
 
-- 
2.25.1

Re: [PATCH 1/2] designprinciples.rst: Perform minor cleanups

[Claudius Heine]

On 2022-07-08 20:38, Tom Rini wrote:
> - Remove some missed wiki markup, and escape a "\n" correctly.
> - Use gender-neutral language to refer to the user, consistently.
> 
> Cc: Claudius Heine <ch@denx.de>
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>   doc/develop/designprinciples.rst | 28 ++++++++++++++--------------
>   1 file changed, 14 insertions(+), 14 deletions(-)
> 
> diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst
> index 79694db77604..b6ceff1aa02b 100644
> --- a/doc/develop/designprinciples.rst
> +++ b/doc/develop/designprinciples.rst
> @@ -18,8 +18,8 @@ relatively small NOR flash memory, which is expensive
>   compared to the much larger NAND devices often used to store the
>   operating system and the application.
>   
> -At the moment, U-Boot supports boards with just 128 !KiB ROM or with
> -256 !KiB NOR flash. We should not easily ignore such configurations -
> +At the moment, U-Boot supports boards with just 128 KiB ROM or with
> +256 KiB NOR flash. We should not easily ignore such configurations -
>   they may be the exception in among all the other supported boards,
>   but if a design uses such a resource-constrained hardware setup it is
>   usually because costs are critical, i. e. because the number of
> @@ -28,15 +28,15 @@ millions...
>   
>   A usable and useful configuration of U-Boot, including a basic
>   interactive command interpreter, support for download over Ethernet
> -and the capability to program the flash shall fit in no more than 128 !KiB.
> +and the capability to program the flash shall fit in no more than 128 KiB.
>   
>   Keep it Fast
>   ^^^^^^^^^^^^
>   
>   The end user is not interested in running U-Boot. In most embedded
> -systems he is not even aware that U-Boot exists. The user wants to
> +systems they are not even aware that U-Boot exists. The user wants to
>   run some application code, and that as soon as possible after switching
> -on his device.
> +on their device.
>   
>   It is therefore essential that U-Boot is as fast as possible,
>   especially that it loads and boots the operating system as fast as possible.
> @@ -62,7 +62,7 @@ Keep it Simple
>   ^^^^^^^^^^^^^^
>   
>   U-Boot is a boot loader, but it is also a tool used for board
> -bring-up, for production testing, and for other activities
> +bring-up, for production testing, and for other activities.
>   
>   Keep it Portable
>   ^^^^^^^^^^^^^^^^
> @@ -95,13 +95,13 @@ Keep it Configurable
>   Section "Keep it Small" already explains about the size restrictions
>   for U-Boot on one side. On the other side, U-Boot is a powerful tool
>   with many, many extremely useful features. The maintainer or user of
> -each board will have to decide which features are important to him and
> -what shall be included with his specific board configuration to meet
> -his current requirements and restrictions.
> +each board will have to decide which features are important to them and
> +what shall be included with their specific board configuration to meet
> +their current requirements and restrictions.
>   
>   Please make sure that it is easy to add or remove features from a
>   board configuration, so everybody can make the best use of U-Boot on
> -his system.
> +their system.
>   
>   If a feature is not included, it should not have any residual code
>   bloating the build.
> @@ -124,7 +124,7 @@ debug is all the more important to many of us.
>   * All initialization steps shall print some "begin doing this" message before
>     they actually start, and some "done" message when they complete. For example,
>     RAM initialization and size detection may print a "RAM: " before they start,
> -  and "256 MB\n" when done.  The purpose of this is that you can always see
> +  and "256 MB\\n" when done.  The purpose of this is that you can always see
>     which initialization step was running if there should be any problem.  This
>     is important not only during software development, but also for the service
>     people dealing with broken hardware in the field.
> @@ -140,8 +140,8 @@ Please always keep in mind that there are at least three different
>   groups of users for U-Boot, with completely different expectations
>   and requirements:
>   
> -* The end user of an embedded device just wants to run some application; he
> -  does not even want to know that U-Boot exists and only rarely interacts with
> +* The end user of an embedded device just wants to run some application; they
> +  do not even want to know that U-Boot exists and only rarely interacts with
>     it (for example to perform a reset to factory default settings etc.)
>   * System designers and engineers working on the development of the application
>     and/or the operating system want a powerful tool that can boot from any boot
> @@ -151,7 +151,7 @@ and requirements:
>     U-Boot to be as simple as possible so porting it to and maintaining it on
>     their hardware is easy for them.
>   * Make it easy to test. Add debug code (but don't re-invent the wheel - use
> -  existing macros like debug() or debugX()).
> +  existing macros like debug()).
>   
>   Please always keep in mind that U-Boot tries to meet all these
>   different requirements.

Reviewed-by: Claudius Heine <ch@denx.de>

Re: [PATCH 2/2] process.rst: Perform minor cleanups

[Claudius Heine]

Hi Tom,

On 2022-07-08 20:38, 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>
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>   doc/develop/process.rst | 31 ++++++++++++++++---------------
>   1 file changed, 16 insertions(+), 15 deletions(-)
> 
> diff --git a/doc/develop/process.rst b/doc/develop/process.rst
> index dd279fb9eff1..8f471fd161b2 100644
> --- a/doc/develop/process.rst
> +++ b/doc/develop/process.rst
> @@ -42,21 +42,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,
>   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
>   --------------------
> @@ -71,13 +72,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 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
> @@ -105,7 +106,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.
> @@ -144,7 +145,7 @@ like this:
>   
>      #. U-Boot Philosophy
>      #. 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:
>   
> @@ -153,7 +154,7 @@ like this:
>        patch should send a short ACK to the mailing list.
>     #. We should create some tool to automatically do 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.
> @@ -161,22 +162,22 @@ like this:
>         sign off/ack lines.
>   
>   5. 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
>      * the list of the affected boards / architectures etc.
>      * 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?
>   

Is this still a todo?

Reviewed-by: Claudius Heine <ch@denx.de>

Re: [PATCH 2/2] process.rst: Perform minor cleanups

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 748 bytes --]

On Mon, Jul 11, 2022 at 10:04:13AM +0200, Claudius Heine wrote:
> Hi Tom,
> 
> On 2022-07-08 20:38, Tom Rini wrote:
[snip]
> >   #. 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?
> 
> Is this still a todo?

Per Heinrich's request, I'm going to reword this section in a follow-up.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]