Add a maintenance process #116
Conversation
|
IMO we can proceed with this if the general shape is right, even if we need to continue iterating on the specifics of the maintenance process for a bit. |
| * Any changes to the Baseline will be reflected within the Compliance Matrix, with new requirements flagged where the Baseline Criteria are appropriate. | ||
| * Downstream stakeholders will be notified via the project's mailing list on the changes and updates. | ||
|
|
||
| ## Identifiers |
There was a problem hiding this comment.
Should this be more specific?
| ## Identifiers | |
| ## Retiring Identifiers for Deprecated Criteria |
There was a problem hiding this comment.
I think this applies to all identifiers, not just deprecated ones. Without a crystal ball, we don't know which identifiers will be deprecated in the future.
There was a problem hiding this comment.
Evan is correct. This is about how identifiers are governed generally (although it is largely driven by discussions around retirement).
There was a problem hiding this comment.
It's about identifier governance in general, because it also covers when and how identifiers can be adjusted between versions (the identifier should "mean" the same thing in the future, so that a tool or document that says Addresses OSPS-XY-46 without explicitly specifying a baseline version is not ambiguous in the future).
I don't know if it's worth explaining that philosophy in this document or not. I tend to like to see the "why" behind rules, but some people find it distracting.
There was a problem hiding this comment.
I'm not sure I quite understand how the branching / releasing strategy will work for future versions -- will we be cutting a release branch for each baseline version? If so, should web-publish be checking out each release branch into a different sub-directory in the future?
(I'm not necessarily asking to do this now, I'm just trying to understand what's being communicated)
| * Any changes to the Baseline will be reflected within the Compliance Matrix, with new requirements flagged where the Baseline Criteria are appropriate. | ||
| * Downstream stakeholders will be notified via the project's mailing list on the changes and updates. | ||
|
|
||
| ## Identifiers |
There was a problem hiding this comment.
I think this applies to all identifiers, not just deprecated ones. Without a crystal ball, we don't know which identifiers will be deprecated in the future.
I don't plan on using branching. I can see the appeal, but I think it makes things like publishing the web content more difficult. So the idea is that when we decide we're releasing, we'd build the current state, check in the output as I didn't include the procedure here because I wanted to keep it to things that consumers care about. What do we think of a |
|
thanks for putting this together @funnelfiasco . I'll put some thought to it and see if I come up with any new feedback beyond what the crew has given so far. |
SecurityCRob
added
documentation
Signed-off-by: Ben Cotton <[email protected]>
funnelfiasco
force-pushed
the
version_management
branch
from
9928d4e to
c7cbf1f
Compare
funnelfiasco
changed the title
|
Repeating from Slack: For the sake of expediency, let's focus on things that are broken or unclear. If something is missing, we can add it in a subsequent PR. |
| * Normal text fixes to the criteria will be accepted via pull request and reviewed by the baseline project maintainers. | ||
| Allowed changes are corrections to spelling/typos, grammar corrections, or enhancements to the supplementary text supporting the criteria, including: Objective, Implementation, Control Mappings, and Scorecard/Insights values. | ||
| At least two project maintainers must review and approve these changes. | ||
| * Substantive changes to Criteria, including changes to text that alters the originally stated meaning, new Criteria proposals, or removal of Criteria will be documented in GitHub PR(s) and reviewed regularly by the Baseline project maintainers. |
There was a problem hiding this comment.
Do you want to stipulate that substantive changes will only take effect in the next released version?
| These changes may reflect changes to global cybersecurity regulations and frameworks or changes in norms around application/project security practices. | ||
| Any such substantive changes must be approved by a majority of the project's maintainers. | ||
| * As appropriate, but at least annually, the Baseline project maintainers will evaluate the set of criteria and, if necessary, publish a new version of the Baseline. | ||
| Previous versions of the Baseline will remain avialable, but are not maintained. |
There was a problem hiding this comment.
Do we want to say "not maintained" or "stable and not subject to change"?
This will undoubtedly require a lot of discussion before it's mergeable, but here's a first pass at addressing #86 and #96, which are related issues.
The gist of my initial draft is that instead of publishing the list of criteria directly to baseline.openssf.org, we publish it to a development version page. The index page has information about the project and links to versions. When we cut a new version, we copy the
development.mdto 'v1.2.md` or whatever we call that version.I took the discussion in #86 as a starting point for the
maintenance.mdpage, with one notable change: I described a process that's more continuous, with versions happening at least once a year (but more often if necessary), instead of keeping criteria sitting as open PRs for long periods.We'll probably want to move some of the contents of
README.mdinto theindex.mdfile (specifically the description of the criteria) and include a link in README to the website instead, but that can be done later. We probably also want to add a "this is a work-in-progress. don't use it for evaluating your project" to the in-development output, and a version/date tag to the "published" versions.