Update baseline.yaml - NEW - OSPS-DO-14 #117
Conversation
suggested wording for OSPS-DO-14 Signed-off-by: CRob <[email protected]>
SecurityCRob
added
documentation
| The project documentation MUST provide a | ||
| descriptive statement when releases or | ||
| versions are no longer supported and that | ||
| will no longer receive security updates. | ||
|
|
||
| This should be provided both in human and | ||
| machine-readable formats. |
There was a problem hiding this comment.
- Do we mean "should" or "SHOULD" in the second sentence? If it's the "normal English 'should'", maybe we actually mean "MUST" instead? (Personally, I lean toward SHOULD, but I want to make sure I understand your intent)
- As a rule, I don't like the idea of multi-sentence criteria and definitely not multi-paragraph (in the
<p>sense, not in the English sense). Could it be be re-written as "The project documentation MUST provide human- and machine-readable descriptive statements when releases are no longer supported and will not longer receive security updates"? (As a note, I condensed "releases or versions" to be "releases" because I'm not entirely clear that there's a meaningful distinction between the two). Or, if the intent was for having both human- and machine-readable be a strong suggestion but not a requirement, then we should move the second sentence into the implementation (which it sort of already is)
| Create a status check that checks the project's | ||
| version control system for support and/or lifecycle | ||
| statements. Publishing this in machine-readble | ||
| formats is preferable. |
There was a problem hiding this comment.
The "implementation" sections should tell projects how to implement it, not how to determine if it's true or not.
Maybe we need a new field, similar to the Best Practices badge's "autofill" field, to describe how a criterion could be automatically determined. Note that the Best Practices Badge has a "details" field that explains how projects can meet the criterion, and I believe that this is what the current "implementation" field is for.
There was a problem hiding this comment.
I'd like for the implementation guidance to projects to be clear enough that someone defining automation can simply read the implementation description to determine how to check it. For example, "Publish support information in $FORMAT_X or $FORMAT_Y, with a link at $LOCATION to the support document."
|
|
||
| This should be provided both in human and | ||
| machine-readable formats. |
There was a problem hiding this comment.
| This should be provided both in human and | |
| machine-readable formats. |
I like machine-processable formats, but I don't know of one for this use. I certainly don't know of any with widespread acceptance. Security-insights.yml can say when the project ends, but I don't think it can do more.
If there is one, please identify that (at least as an option) in the "implementation" section.
| statements. Publishing this in machine-readble | ||
| formats is preferable. |
There was a problem hiding this comment.
Do we have any examples of machine-readable formats here? I 100% support using machine-readable formats, but it feels like the "implementation" section would be a good place to link to one or more examples if they exist.
There was a problem hiding this comment.
Maybe reference OpenEoX and/or endoflife.date? I'm torn between preferring a halfway solution over complete uncertainty, and lacking much evidence that the format works.
| Create a status check that checks the project's | ||
| version control system for support and/or lifecycle | ||
| statements. Publishing this in machine-readble | ||
| formats is preferable. |
There was a problem hiding this comment.
I'd like for the implementation guidance to projects to be clear enough that someone defining automation can simply read the implementation description to determine how to check it. For example, "Publish support information in $FORMAT_X or $FORMAT_Y, with a link at $LOCATION to the support document."
suggested wording for OSPS-DO-14 for End-Of-Support statement