#vnfrqts PNP text > SHOULD vs SHALL #vnfrqts
|
Zu Qiang
English is not my first language. But I believe Steven can help with this. In standardization English language, both “SHALL” and “MUST” means “REQUIRED”. For instance, 3GPP is using “SHALL” and IETF is using “MUST”. “SHOULD” means “RECOMMENDED”. “MAY” means “OPTIONAL”. For more details, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Sent: Monday, September 10, 2018 7:54 AM To: Zu Qiang <zu.qiang@...>; WRIGHT, STEVEN A <sw3588@...> Cc: 'onap-discuss@...' <onap-discuss@...>; Hillis, Marge (Nokia - US) <marge.hillis@...> Subject: RE: #vnfrqts PNP text > SHOULD vs SHALL
All,
REQUIREMENTS TEXT should be using “SHALL” not “SHOULD”.
I SHOULD have gone to the market. (PAST Tense desire) He SHALL go to the market. (Indicates that REQUIRED future need) The system SHOULD have activated the LED (but it was too late). The system SHALL activate the LED (when xyz occurs).
Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
shall SHal,SHəl/ verb modal verb: shall 1. (in the first person) expressing the future tense. "this time next week I shall be in Scotland" 2. expressing a strong assertion or intention. "they shall succeed"
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven According to the vnf requirement section 3, “Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.” Unfortunately, RFC2119 is specified in last century. Do we have any plan to update that requirement by including “SHALL” as normative text in Casablanca?
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Qiang Zu, · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · [BEN] – I have rechecked my text … All of the requirements do have “Should”/“Shall”, or “May”. After 20 years of writing requirements that is a rare mistake for me to make. I have highlighted this in red text below (in this email thread). · · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · [BEN] – I COMPLETELY disagree!!! The usefulness of a Wiki and hyperlinks is that a reader can find out related and other relevant information which I think is very appropriate and useful. That is why a Wiki is more useful than a traditional paper “static” dictionary or encyclopedia. This was the fundamental invention of HTTP (Hypertext), welcome to the 21st century. · · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · [BEN] – I can remove the one R4 requirement, [1300] · · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. · [BEN] – I COMPLETELY disagree with this notion. If there is “non-normative” requirements text (text that is not “shall/should”, “must”, “may”), it shall belong to a note – this can help a reader understand why a requirement is structured or worded the way it is. Clarifying text or notes are a way for the author to convey vital background that might be needed to describe engineering decisions, and the logical through processes of the systems engineer. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven The following is my comment on the Jira page which no response is received yet.
hello, Benjamin Cheung, Thanks for updating the requirements text. I have some general comments here: · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Have a nice day Zu Qiang
|
|
|
|
Zu Qiang
Hello, Ben Thank you for your excellent explanation of the English words. Normative text is an ISO terminology and supported by each standardization origination, which you cannot find in any dictionary. For instance, IETF is using MUST/SHOULD/MAY as specified in RFC2119, which is a standardization community agreement made 20 years ago. ONAP is following the IETF way as defined in section 3 of the VNF requirement document. But 3GPP is using SHALL/SHOULD/MAY as specified in 3GPP TR21.801. 3GPP2 has same definition in 3GPP2 SC.R1005. You shall not assume that ONAP is going to use the same normative text which is used in another RAN standardization origination. As I recommended early, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Sent: Monday, September 10, 2018 9:13 AM To: Zu Qiang <zu.qiang@...>; WRIGHT, STEVEN A <sw3588@...> Cc: 'onap-discuss@...' <onap-discuss@...>; Hillis, Marge (Nokia - US) <marge.hillis@...> Subject: RE: #vnfrqts PNP text > SHOULD vs SHALL
Zu Qiang,
English is my primary language. Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
There is also a second sense indicating a strength of assertion. In 20 years of writing requirements for RAN systems we have always used “SHALL” instead of “SHOULD”.
shall SHal,SHəl/ verb modal verb: shall
should SHo͝od,SHəd/ verb modal verb: should 1. used to indicate obligation, duty, or correctness, typically when criticizing someone's actions. 2. used to indicate what is probable.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
English is not my first language. But I believe Steven can help with this. In standardization English language, both “SHALL” and “MUST” means “REQUIRED”. For instance, 3GPP is using “SHALL” and IETF is using “MUST”. “SHOULD” means “RECOMMENDED”. “MAY” means “OPTIONAL”. For more details, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
All,
REQUIREMENTS TEXT should be using “SHALL” not “SHOULD”.
I SHOULD have gone to the market. (PAST Tense desire) He SHALL go to the market. (Indicates that REQUIRED future need) The system SHOULD have activated the LED (but it was too late). The system SHALL activate the LED (when xyz occurs).
Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
shall SHal,SHəl/ verb modal verb: shall
2. expressing a strong assertion or intention. "they shall succeed"
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven According to the vnf requirement section 3, “Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.” Unfortunately, RFC2119 is specified in last century. Do we have any plan to update that requirement by including “SHALL” as normative text in Casablanca?
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Qiang Zu, · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · [BEN] – I have rechecked my text … All of the requirements do have “Should”/“Shall”, or “May”. After 20 years of writing requirements that is a rare mistake for me to make. I have highlighted this in red text below (in this email thread). · · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · [BEN] – I COMPLETELY disagree!!! The usefulness of a Wiki and hyperlinks is that a reader can find out related and other relevant information which I think is very appropriate and useful. That is why a Wiki is more useful than a traditional paper “static” dictionary or encyclopedia. This was the fundamental invention of HTTP (Hypertext), welcome to the 21st century. · · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · [BEN] – I can remove the one R4 requirement, [1300] · · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. · [BEN] – I COMPLETELY disagree with this notion. If there is “non-normative” requirements text (text that is not “shall/should”, “must”, “may”), it shall belong to a note – this can help a reader understand why a requirement is structured or worded the way it is. Clarifying text or notes are a way for the author to convey vital background that might be needed to describe engineering decisions, and the logical through processes of the systems engineer. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven The following is my comment on the Jira page which no response is received yet.
hello, Benjamin Cheung, Thanks for updating the requirements text. I have some general comments here: · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Have a nice day Zu Qiang
|
|
|
|
Zu Qiang, Ben,
The rest of the VNFRQTS are defined using the RC2119 keywords, and I'd rather not change that at this point. If you are adapting some text from elsewhere ( 3GPP?) then translating a SHALL"-> "MUST" would normally work based on the definition in RFC2119. regards Steven Wright
|
|
|
|
Zu Qiang
Hello, Ben With over 30 years standardization working experience, I do understand your confusions. First of all, “SHOULD” is defined in the RFC with the meaning “RECOMMENDED”, not past tense of “shall”. Second, using MUST or SHALL or both as “REQUIRED” is an ONAP community decision. Steven shall clarify it as I asked in my early email: “According to the vnf requirement section 3, “Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.” Unfortunately, RFC2119 is specified in last century. Do we have any plan to update that requirement by including “SHALL” as normative text in Casablanca?” (Personally, I don’t think we should.)
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Sent: Monday, September 10, 2018 12:58 PM To: Zu Qiang <zu.qiang@...>; WRIGHT, STEVEN A <sw3588@...> Cc: 'onap-discuss@...' <onap-discuss@...>; Hillis, Marge (Nokia - US) <marge.hillis@...> Subject: RE: #vnfrqts PNP text > SHOULD vs SHALL
Zu Qiang,
RFC2119 definitely allows you to use the word “SHALL” (See below)
Text using “Must Not” and “Should Not” are not requirements! There are a million things that a PNF must not and should not do … for example a PNF shall not eat lobsters, a PNF shall not cross the street, a PNF shall not buy tulips. You can replace these verb-objects with anything else they are just as meaningless.
As a systems engineer you shall always specify in the “positive” text of what needs to be done.
[Docs] [txt|pdf]
[draft-bradner-k...] [Tracker]
[Diff1] [Diff2]
[Errata] Network Working Group S. Bradner
Request for Comments: 2119 Harvard University
BCP: 14 March 1997
Category: Best Current Practice
Key words for use in RFCs to Indicate Requirement Levels
Status of this Memo
This document specifies an Internet Best Current Practices for the
Internet Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.
Abstract
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
Note that the force of these words is modified by the requirement
level of the document in which they are used.
1. MUSTThis word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.
3. SHOULD This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.
4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
particular behavior is acceptable or even useful, but the full
implications should be understood and the case carefully weighed
before implementing any behavior described with this label.
Bradner Best Current Practice [Page 1]
RFC 2119 RFC Key Words March 1997
5. MAY This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One vendor may choose to include the item because a
particular marketplace requires it or because the vendor feels that
it enhances the product while another vendor may omit the same item.
An implementation which does not include a particular option MUST be
prepared to interoperate with another implementation which does
include the option, though perhaps with reduced functionality. In the
same vein an implementation which does include a particular option
MUST be prepared to interoperate with another implementation which
does not include the option (except, of course, for the feature the
option provides.)
Bradner Best Current Practice [Page 2]
RFC 2119 RFC Key Words March 1997 Bradner Best Current Practice [Page 3]
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Ben Thank you for your excellent explanation of the English words. Normative text is an ISO terminology and supported by each standardization origination, which you cannot find in any dictionary. For instance, IETF is using MUST/SHOULD/MAY as specified in RFC2119, which is a standardization community agreement made 20 years ago. ONAP is following the IETF way as defined in section 3 of the VNF requirement document. But 3GPP is using SHALL/SHOULD/MAY as specified in 3GPP TR21.801. 3GPP2 has same definition in 3GPP2 SC.R1005. You shall not assume that ONAP is going to use the same normative text which is used in another RAN standardization origination. As I recommended early, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Zu Qiang,
English is my primary language. Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
There is also a second sense indicating a strength of assertion. In 20 years of writing requirements for RAN systems we have always used “SHALL” instead of “SHOULD”.
shall SHal,SHəl/ verb modal verb: shall 1. (in the first person) expressing the future tense. "this time next week I shall be in Scotland" 2. expressing a strong assertion or intention. "they shall succeed" should SHo͝od,SHəd/ verb modal verb: should 1. used to indicate obligation, duty, or correctness, typically when criticizing someone's actions. 2. used to indicate what is probable.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
English is not my first language. But I believe Steven can help with this. In standardization English language, both “SHALL” and “MUST” means “REQUIRED”. For instance, 3GPP is using “SHALL” and IETF is using “MUST”. “SHOULD” means “RECOMMENDED”. “MAY” means “OPTIONAL”. For more details, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
All,
REQUIREMENTS TEXT should be using “SHALL” not “SHOULD”.
I SHOULD have gone to the market. (PAST Tense desire) He SHALL go to the market. (Indicates that REQUIRED future need) The system SHOULD have activated the LED (but it was too late). The system SHALL activate the LED (when xyz occurs).
Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
shall SHal,SHəl/ verb modal verb: shall
2. expressing a strong assertion or intention. "they shall succeed"
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven According to the vnf requirement section 3, “Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.” Unfortunately, RFC2119 is specified in last century. Do we have any plan to update that requirement by including “SHALL” as normative text in Casablanca?
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Qiang Zu, · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · [BEN] – I have rechecked my text … All of the requirements do have “Should”/“Shall”, or “May”. After 20 years of writing requirements that is a rare mistake for me to make. I have highlighted this in red text below (in this email thread). · · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · [BEN] – I COMPLETELY disagree!!! The usefulness of a Wiki and hyperlinks is that a reader can find out related and other relevant information which I think is very appropriate and useful. That is why a Wiki is more useful than a traditional paper “static” dictionary or encyclopedia. This was the fundamental invention of HTTP (Hypertext), welcome to the 21st century. · · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · [BEN] – I can remove the one R4 requirement, [1300] · · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. · [BEN] – I COMPLETELY disagree with this notion. If there is “non-normative” requirements text (text that is not “shall/should”, “must”, “may”), it shall belong to a note – this can help a reader understand why a requirement is structured or worded the way it is. Clarifying text or notes are a way for the author to convey vital background that might be needed to describe engineering decisions, and the logical through processes of the systems engineer. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven The following is my comment on the Jira page which no response is received yet.
hello, Benjamin Cheung, Thanks for updating the requirements text. I have some general comments here: · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Have a nice day Zu Qiang
|
|
|
|
Zu Qiang
+1
Have a nice day Zu Qiang
From: onap-discuss@... <onap-discuss@...>
On Behalf Of WRIGHT, STEVEN A
Sent: Monday, September 10, 2018 12:41 PM To: onap-discuss@... Subject: Re: [onap-discuss] #vnfrqts PNP text > SHOULD vs SHALL
Zu Qiang, Ben,
|
|
|
|
Zu Qiang
Hello, Ben The following is the response from Steven Wright, which I totally agree with him. But if you would like to change the ONAP community decision, may be you should call in the VNGRQTS meeting tomorrow at 8am (New York time zone). “Zu Qiang, Ben,
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Sent: Monday, September 10, 2018 2:37 PM To: Zu Qiang <zu.qiang@...>; WRIGHT, STEVEN A <sw3588@...> Cc: 'onap-discuss@...' <onap-discuss@...>; Hillis, Marge (Nokia - US) <marge.hillis@...> Subject: RE: #vnfrqts PNP text > SHOULD vs SHALL
Zu Qiang,
Throughout your email you assert that we should not use the word “SHALL” which is patently absurd.
Even in RFC2119 there is provision for the use of the word Shall. And it is never good when you start throwing the “bible” at people!
We shall do what is logical and makes sense to our customers: the readers, developers, architects, and testers.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Ben With over 30 years standardization working experience, I do understand your confusions. First of all, “SHOULD” is defined in the RFC with the meaning “RECOMMENDED”, not past tense of “shall”. Second, using MUST or SHALL or both as “REQUIRED” is an ONAP community decision. Steven shall clarify it as I asked in my early email: “According to the vnf requirement section 3, “Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.” Unfortunately, RFC2119 is specified in last century. Do we have any plan to update that requirement by including “SHALL” as normative text in Casablanca?” (Personally, I don’t think we should.)
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Zu Qiang,
RFC2119 definitely allows you to use the word “SHALL” (See below)
Text using “Must Not” and “Should Not” are not requirements! There are a million things that a PNF must not and should not do … for example a PNF shall not eat lobsters, a PNF shall not cross the street, a PNF shall not buy tulips. You can replace these verb-objects with anything else they are just as meaningless.
As a systems engineer you shall always specify in the “positive” text of what needs to be done.
[Docs] [txt|pdf]
[draft-bradner-k...] [Tracker]
[Diff1] [Diff2]
[Errata] Network Working Group S. Bradner
Request for Comments: 2119 Harvard University
BCP: 14 March 1997
Category: Best Current Practice
Key words for use in RFCs to Indicate Requirement Levels
Status of this Memo
This document specifies an Internet Best Current Practices for the
Internet Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.
Abstract
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
Note that the force of these words is modified by the requirement
level of the document in which they are used.
1. MUSTThis word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.
3. SHOULD This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.
4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
particular behavior is acceptable or even useful, but the full
implications should be understood and the case carefully weighed
before implementing any behavior described with this label.
Bradner Best Current Practice [Page 1]
RFC 2119 RFC Key Words March 1997
5. MAY This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One vendor may choose to include the item because a
particular marketplace requires it or because the vendor feels that
it enhances the product while another vendor may omit the same item.
An implementation which does not include a particular option MUST be
prepared to interoperate with another implementation which does
include the option, though perhaps with reduced functionality. In the
same vein an implementation which does include a particular option
MUST be prepared to interoperate with another implementation which
does not include the option (except, of course, for the feature the
option provides.)
Bradner Best Current Practice [Page 2]
RFC 2119 RFC Key Words March 1997 Bradner Best Current Practice [Page 3]
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Ben Thank you for your excellent explanation of the English words. Normative text is an ISO terminology and supported by each standardization origination, which you cannot find in any dictionary. For instance, IETF is using MUST/SHOULD/MAY as specified in RFC2119, which is a standardization community agreement made 20 years ago. ONAP is following the IETF way as defined in section 3 of the VNF requirement document. But 3GPP is using SHALL/SHOULD/MAY as specified in 3GPP TR21.801. 3GPP2 has same definition in 3GPP2 SC.R1005. You shall not assume that ONAP is going to use the same normative text which is used in another RAN standardization origination. As I recommended early, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Zu Qiang,
English is my primary language. Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
There is also a second sense indicating a strength of assertion. In 20 years of writing requirements for RAN systems we have always used “SHALL” instead of “SHOULD”.
shall SHal,SHəl/ verb modal verb: shall 1. (in the first person) expressing the future tense. "this time next week I shall be in Scotland" 2. expressing a strong assertion or intention. "they shall succeed" should SHo͝od,SHəd/ verb modal verb: should 1. used to indicate obligation, duty, or correctness, typically when criticizing someone's actions. 2. used to indicate what is probable.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
English is not my first language. But I believe Steven can help with this. In standardization English language, both “SHALL” and “MUST” means “REQUIRED”. For instance, 3GPP is using “SHALL” and IETF is using “MUST”. “SHOULD” means “RECOMMENDED”. “MAY” means “OPTIONAL”. For more details, please read RFC2119.
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
All,
REQUIREMENTS TEXT should be using “SHALL” not “SHOULD”.
I SHOULD have gone to the market. (PAST Tense desire) He SHALL go to the market. (Indicates that REQUIRED future need) The system SHOULD have activated the LED (but it was too late). The system SHALL activate the LED (when xyz occurs).
Difference Between Shall and Should. The basic difference between “shall” and “should” is that “should” is the past tense of “shall.” ... “Should” is the conditional form used for “shall.” Occasionally it is used as a past tense of “shall.”
shall SHal,SHəl/ verb modal verb: shall
2. expressing a strong assertion or intention. "they shall succeed"
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven According to the vnf requirement section 3, “Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.” Unfortunately, RFC2119 is specified in last century. Do we have any plan to update that requirement by including “SHALL” as normative text in Casablanca?
Have a nice day Zu Qiang
From: Cheung, Ben (Nokia - US/Murray Hill) <ben.cheung@...>
Qiang Zu, · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · [BEN] – I have rechecked my text … All of the requirements do have “Should”/“Shall”, or “May”. After 20 years of writing requirements that is a rare mistake for me to make. I have highlighted this in red text below (in this email thread). · · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · [BEN] – I COMPLETELY disagree!!! The usefulness of a Wiki and hyperlinks is that a reader can find out related and other relevant information which I think is very appropriate and useful. That is why a Wiki is more useful than a traditional paper “static” dictionary or encyclopedia. This was the fundamental invention of HTTP (Hypertext), welcome to the 21st century. · · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · [BEN] – I can remove the one R4 requirement, [1300] · · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. · [BEN] – I COMPLETELY disagree with this notion. If there is “non-normative” requirements text (text that is not “shall/should”, “must”, “may”), it shall belong to a note – this can help a reader understand why a requirement is structured or worded the way it is. Clarifying text or notes are a way for the author to convey vital background that might be needed to describe engineering decisions, and the logical through processes of the systems engineer. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Best regards, -Ben Cheung, PhD, DMTS, ALTA ATF Architecture Systems Engineer Mobile Networks, Nokia Tel +1 (908) 679-6615 Email Ben.Cheung@... 600-700 Mountain Ave, Murray Hill, NJ 07974-0636 USA / #2C-378
From: Zu Qiang [mailto:zu.qiang@...]
Hello, Steven The following is my comment on the Jira page which no response is received yet.
hello, Benjamin Cheung, Thanks for updating the requirements text. I have some general comments here: · Is the requirements list in your comment the revised requirements only? You can move the proposed text into description section to avoid confusion. · Please use the normative text "MUST", "SHOULD", "MAY" as requested in section 3 · The reference to the 5G PnP wiki page must be removed. The 5G PnP wiki has too many non-normative text. · Any requirements beyond Casablanca release must be removed. If we believe the function will be implemented in Dublin, we can keep the requirements in a new Jira tickets in backlog. · We should keep the normative text only and remove all the explanation text in the notes. If anyone would like to have a better understanding on how the 5G PnP works, he/she should read the 5G PnP wiki page. I'll come back with some detail rewording proposals if we can have an agreement on the general part first.
Have a nice day Zu Qiang
|
|
|