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

[Frank Kühndel]

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>> wrote:
> 
>     From: Frank Kühndel <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

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>
>     http://lists.rtems.org/mailman/listinfo/devel
>     <http://lists.rtems.org/mailman/listinfo/devel>
> 

Greetings
Frank