[PATCH v2] eng: Requirements counting shall start at zero

[Frank Kühndel]

Hello Gedare,

On 12/11/20 4:41 PM, Gedare Bloom wrote:
> 
> 
> On Fri, Dec 11, 2020 at 8:16 AM Frank Kühndel
> <frank.kuehndel at embedded-brains.de
> <mailto:frank.kuehndel at embedded-brains.de>> wrote:
> 
>     Hello Joel,
> 
>     On 12/11/20 3:49 PM, Joel Sherrill wrote:
>     >
>     >
>     > On Fri, Dec 11, 2020, 8:41 AM Frank Kuehndel
>     > <frank.kuehndel at embedded-brains.de
>     <mailto:frank.kuehndel at embedded-brains.de>
>     > <mailto:frank.kuehndel at embedded-brains.de
>     <mailto:frank.kuehndel at embedded-brains.de>>> wrote:
>     >
>     >     From: Frank Kühndel <frank.kuehndel at embedded-brains.de
>     <mailto:frank.kuehndel at embedded-brains.de>
>     >     <mailto:frank.kuehndel at embedded-brains.de
>     <mailto:frank.kuehndel at embedded-brains.de>>>
>     >
>     >     ---
>     >      eng/req/req-for-req.rst | 21 +++++++++++++++++++++
>     >      1 file changed, 21 insertions(+)
>     >
>     >     diff --git a/eng/req/req-for-req.rst b/eng/req/req-for-req.rst
>     >     index 9225e95..dcc4c11 100644
>     >     --- a/eng/req/req-for-req.rst
>     >     +++ b/eng/req/req-for-req.rst
>     >     @@ -308,6 +308,27 @@ spec:/classic/task/create-err-invname
>     >
>     >          ...
>     >
>     >     +If requirements or the YAML files which contain them are to be
>     >     numbered,
>     >     +the numbering shall start with 0. For example:
>     >
>     >     +
>     >     +.. code-block:: none
>     >     +
>     >     +    weak-alias-0.yml
>     >     +    weak-alias-1.yml
>     >     +
>     >     +Smaller numbers shall be prefixed with 0 to the same count of
>     digits
>     >     +as the largest number. For example:
>     >
>     >
>     > When one goes from 99 to 100 requirements and didn't anticipate having
>     > that many, does this mean all the files will have to be renamed?
> 
>     I can change the text to what Gedare Bloom suggested: "If we know the
>     max count (N) ahead of time, ..."
> 
>     Just from my experience with the requirements for the basedefs, when I
>     create the requirements for an operation, I know the number I end up
>     with before checking them in. The issue we discuss would only cause
>     trouble if later more requirements for the same operation must be added.
>     This is not totally unlikely but it means that one actually has 9 and
>     then need a 10th one.
> 
>     >
>     > Should we start with a minimum of three or four digits? What would
>     drive
>     > the number of requirements in a set? How large of a functional
>     area will
>     > a single numbered set contain?
>     >
>     > I'm just wondering if it is simpler to just have 001 as a minimum.
> 
>     I think that 99 requirements for a single operation are really out of
>     scope. That will hopefully never ever happen. Even 9 is already a lot.
>     Also it is rather advisable to adapt the names of the requirements to
>     indicate the purpose. The numbering is more for the case that there are
>     two or more requirements on the same topic (like on handling the same
>     bad input argument).
> 
>       my-function-0
>       my-function-1
>       my-function-global-side-effect
>       my-function-bad-argument-x-error-handling
>       my-function-bad-argument-y-error-handling
>       my-function-called-in-wrong-state
> 
> 
> This actually means there is a requirement for unnumbered names as well.
> 
> Would it be better to explicitly define all requirements numbered and
> use -0, in case they should be extended later, or perhaps to start
> numbering without a number as 0 "implied" and numbers begin with 1?
> 

If there is a -1 then I personally prefer that there should be a -0. For
the basedefs, I ended all requirements with -0 even if there was no -1.
Yet, whether this is the most wisest thing to do, I cannot say. I would
leave it to the author.

These numbers are mainly for requirements which need to be split:

  my-function.yml
    "The function shall return 7 and set global variable X to 5".

If later someone needs to split this, would renaming it be so much trouble?

  my-function-0.yml
    "The function shall return 7".

  my-function-1.yml
    "The function shall set global variable X to 5".

Could be as well:

  my-function-result.yml
    "The function shall return 7".

  my-function-side-effect.yml
    "The function shall set global variable X to 5".

Greetings
Frank

> 
>     My opinion is that defining whether we start counting with 0 or with 1
>     makes sense. Everything else seems to me a bit like solving theoretical
>     problems.
> 
>     >
>     >     +
>     >     +.. code-block:: none
>     >     +
>     >     +    alias-00.yml
>     >     +    alias-01.yml
>     >     +    alias-02.yml
>     >     +    ...
>     >     +    alias-09.yml
>     >     +    alias-10.yml
>     >     +    alias-11.yml
>     >     +
>     >      Conflict Free Requirements
>     >      --------------------------
>     >
>     >     --
>     >     2.26.2
>     >
>     >     _______________________________________________
>     >     devel mailing list
>     >     devel at rtems.org <mailto:devel at rtems.org>
>     <mailto:devel at rtems.org <mailto:devel at rtems.org>>
>     >     http://lists.rtems.org/mailman/listinfo/devel
>     <http://lists.rtems.org/mailman/listinfo/devel>
>     >     <http://lists.rtems.org/mailman/listinfo/devel
>     <http://lists.rtems.org/mailman/listinfo/devel>>
>     >
> 
>     Greetings
>     Frank
>     _______________________________________________
>     devel mailing list
>     devel at rtems.org <mailto:devel at rtems.org>
>     http://lists.rtems.org/mailman/listinfo/devel
>     <http://lists.rtems.org/mailman/listinfo/devel>
>