[PATCH v2] eng: Requirements counting shall start at zero
Joel Sherrill
joel at rtems.org
Fri Dec 11 16:43:14 UTC 2020
On Fri, Dec 11, 2020 at 10:38 AM Gedare Bloom <gedare at rtems.org> wrote:
>
>
> 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.
>
+1
I would be concerned that the unnumbered ones would be following a
different naming pattern which would make the requirements file matching
pattern harder.
>
>
>> 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/7308d151/attachment-0001.html>
More information about the devel
mailing list