Skip to content

Updates to Documentation criteria missing rationale and implementation details #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eddie-knight merged 4 commits into from
Feb 18, 2025
Merged

Updates to Documentation criteria missing rationale and implementation details #159

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
01eea58
Updates to Documentation criteria missing rationale and implementatio…
SecurityCRob Jan 24, 2025
e0a6cb3
Update OSPS-DO.yaml
SecurityCRob Jan 27, 2025
f5466ca
Added OpenEoX lexicon entry and updated criteria
eddie-knight Feb 17, 2025
9491904
simplified DO-15 text
eddie-knight Feb 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 61 additions & 7 deletions baseline/OSPS-DO.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,15 +100,30 @@ criteria:
The project documentation MUST include a
descriptive statement about the scope and
duration of support.
rationale: # TODO
# TODO: Integrate with advice from https://endoflife.date/recommendations
rationale: |
Stating the support expecations the project
has (in this case when the project will no
longer be actively supporting the project and
considering it "end of life") are important
for downstream consumers to be aware of
and understand so they can take relevant actions
to ensure the required functionality can still
be achieved.
implementation: |
The project should have either a "Support"
header in the README, a SUPPORT.md file
present in the repo root, or a SUPPORT.eox
file in the [OpenEOX format](https://github.com/OpenEoX/openeox/blob/main/schema/schema.json)
describing the scope and duration of support
for the project's released software assets.

[endoflife.date](https://endoflife.date/recommendations)
provides concrete examples of real-life projects (both good
and bad) communicating their end of support.

Alternatively, the project could published their
desired support and duration through such outlets
as a project blog, mailing list, or FAQ.
Copy link
Contributor

@evankanderson evankanderson Jan 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the challenge here (and part of why this should be level 2 or level 3) is that there is no standard place to find this information for a project. For example, Istio data is fetched from https://istio.io/latest/docs/releases/supported-releases/, parsed through the selector: table argument and then run through a few regexes ('^~?(?P<value>\w+ \d+(, \d+)?).*', for example).

I'd love to see some better standards here, but I'm nervous about making this a requirement without a clear way to measure compliance or for consumers to use the result. If we want to push security-insights, we could try to enforce that as a mechanism, though I think current adoption is fairly low.

Copy link
Contributor Author

@SecurityCRob SecurityCRob Jan 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As much as I desire one location to store this, it has never naturally developed over the last decade(s). As we roll this out as a standard for LF projects, we could be more prescriptive with how this should be implemented (and automated/templatetize it for our projects) then as others saw it, they could possibly adopt that location.

Copy link
Contributor

@evankanderson evankanderson Jan 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's what I'm advocating for. I think it's okay to take one or two items and say "hey, here's a standard place to put this" and people will either create the file or symlink it if the requirements are fairly easy to fit with their existing content. In turn, that will make the work of folks like endoflife.date easier.

I suspect it's part of a more-mature project, so at least level 2 (my other PR, no need to include it here).

Copy link
Contributor

@evankanderson evankanderson Jan 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing that occurred in discussion this week in Minder was that projects using GitHub releases could actually update existing releases to include some release text indicating when a release is out of support.

I'm not sure what similar options are available for container images, helm charts, and language packages.

Copy link
Contributor

@evankanderson evankanderson Feb 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My $0.02 is that DO-14 is more practical for non-archived (unsupported) projects. People often don't know until after it's done that a project will be unmaintained in a few months or a year.

Relying on the archived bit seems tricky -- how do you distinguish between a project which is "done" (e.g. https://github.com/yosida95/uritemplate) and a project which is abandoned to the point that no one can hit "archive"?

The best I've come up with is having some sort of sentinel "heartbeat" file that needs to be touched every ~year that says "In 2025, this project was supported by $entity".

Maybe we could pivot this to that format?

control_mappings:
BPB: R-B-3
SSDF: PO4.2, PS3.1, RV1.3
Expand All @@ -123,8 +138,28 @@ criteria:
descriptive statement when releases or
versions are no longer supported and that
will no longer receive security updates.
rationale: # TODO
implementation: # TODO
rationale: |
Communicating when the project will no longer
be suipported and/or will no longer fix
defects or security vulnerabilities is
crucial for downstream consumers to be
made aware of so they may take appropriate
actions to find alternative to the project
or find alternative means of support for the
provided functionality.
implementation: |
[OpenEOX format](https://github.com/OpenEoX/openeox/blob/main/schema/schema.json)
from OASIS is a machine-readable method to
express the state of lifecycle.

[endoflife.date](https://endoflife.date/recommendations)
provides concrete examples of real-life projects (both good
and bad) communicating their end of support.

Alternatively, the project could provide notice through
a project blog, issue, mailing list, or other means
that community leverages to communicate
project updates
control_mappings:
CRA: 1.2c, 2.6
OC: 4.1.1, 4.3.1
Expand All @@ -133,13 +168,32 @@ criteria:

- id: OSPS-DO-15
maturity_level: 2
category: Vulnerability Management
category: Documentation
criterion: |
The project documentation MUST include a
description of how the project selects,
obtains, and tracks its dependencies.
rationale: # TODO
implementation: # TODO
rationale: |
Providing information about how the project
selects, obtains, and tracks dependencies,
libraries, frameworks, etc. help downstream
consumers understand how the project operates
in regards to third-party components that are
required neccessary for the software to function.

This information also helps inform downstream
consumer of key third-party components they
should be monitoring.
implementation: |
Ideally this information is captured along with the
projects technical & design documentation and
available through a publicy viewable resource
such as the source code repository, project website,
or other channel.

Having a "dependencies" header in CONTRIBUTING.md or
equivalent contributing documentation could fulfill
this criteria.
control_mappings:
BPB: A-S-1
CRA: 2.1
Expand Down
Loading