kaboomstandardsorganization/rfcs

Fork 2

RFC 0000: Explain what soft/hard requirements are #3

Open

opt wants to merge 1 commit from opt/rfcs:requirements-explanation into main

opt commented

2024-10-17 20:08:34 -04:00

Owner

Pull request to resolve issues behind #2

opt force-pushed requirements-explanation from e510f5fba8 to 38806c0201

2024-10-17 20:09:37 -04:00

Compare

opt referenced this pull request

2024-10-17 20:12:13 -04:00

Use of RFC2119 in KSO/RFC0000 #2

requested reviews from chipmunkmc, amy, khy, hhhzzzsss

2024-10-17 20:12:28 -04:00

amy requested changes

2024-10-17 20:59:01 -04:00

Dismissed

amy left a comment

Owner

I think we should just do what Dinhero said and just use RFC 2119 for this. Here's what it defines for "must" and "should":

MUST This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.

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.

This is pretty much exactly what we're specifying, it's just more verbose.

Here's how the RFC tells people to use it:

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.

I think we should just do what Dinhero said and just use RFC 2119 for this. Here's what it defines for "must" and "should": > 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the > definition is an absolute requirement 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. This is pretty much exactly what we're specifying, it's just more verbose. Here's how the RFC tells people to use it: > 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.

opt commented

2024-10-18 03:08:02 -04:00

Author

Owner

I think we should just do what Dinhero said and just use RFC 2119 for this. Here's what it defines for "must" and "should":

MUST This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.

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.

This is pretty much exactly what we're specifying, it's just more verbose.

Here's how the RFC tells people to use it:

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.

To avoid confusion, I will henceforth be referring to RFC 2119 as "the RFC", and the genesis RFC contained in this repository as "the KRFC".

Unfortunately, I feel the language is too complicated for this project. At the very minimum, if these definitions are included in the KRFC, they will have to be cut down. This is why I have written my own version similar enough to what the RFC states, but simple enough to keep within the bounds of the KRFC.

> I think we should just do what Dinhero said and just use RFC 2119 for this. Here's what it defines for "must" and "should": > > 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the > > definition is an absolute requirement 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. > > This is pretty much exactly what we're specifying, it's just more verbose. > > Here's how the RFC tells people to use it: > > > 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. To avoid confusion, I will henceforth be referring to RFC 2119 as "the RFC", and the genesis RFC contained in this repository as "the KRFC". Unfortunately, I feel the language is too complicated for this project. At the very minimum, if these definitions are included in the KRFC, they will have to be cut down. This is why I have written my own version similar enough to what the RFC states, but simple enough to keep within the bounds of the KRFC.

amy commented

2024-10-19 09:56:04 -04:00

Owner

That's fair.

amy approved these changes

2024-10-19 09:56:10 -04:00

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u requirements-explanation:opt-requirements-explanation

git switch opt-requirements-explanation

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff opt-requirements-explanation

git switch opt-requirements-explanation

git rebase main

git switch main

git merge --ff-only opt-requirements-explanation

git switch opt-requirements-explanation

git rebase main

git switch main

git merge --no-ff opt-requirements-explanation

git switch main

git merge --squash opt-requirements-explanation