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

Gedare Bloom gedare at rtems.org
Fri Dec 11 16:38:34 UTC 2020


On Fri, Dec 11, 2020 at 9:12 AM Frank Kühndel <
frank.kuehndel at embedded-brains.de> wrote:

> 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?
>
> I don't know if renaming them would be a problem or not. Need an expert to
weigh in on that.

If renaming them introduces challenges, then we should explicitly use -0
for the first requirement always, and not allow unnumbered ones to exist.


>   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>
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201211/f128db9e/attachment.html>


More information about the devel mailing list