Migrate to Community Specification license and governance

[swinslow]

(This is a follow-on from #236 -- following from conversation with @kimsterv yesterday, thought that it might make sense to open a new issue thread with the updates.)

As previously discussed by the community and reflected in the OpenSSF charter section 5(a)(iii), specifications under OpenSSF should use the Community Specification license and its related governance processes.

The default Community Specification process is intended for use where a project has a single repo, and needs some tweaking to work as expected in multi-repo orgs. It also comes with a limited set of participant roles that don't necessarily map to how pre-existing projects operate.

Based on conversations with the community, I've prepared a customized version of the Community Specification repo at https://github.com/swinslow/slsa-governance. I've set up the various documents to work with the way that SLSA intends to operate the spec development process.

I think the intent would be to migrate that repo to be hosted at https://github.com/slsa-framework/governance. Since I can't create a PR for that move, I'm filing this issue so that the SLSA community can migrate the repo once they're ready to do so. Feel free to let me know if you have any questions about the draft documents in the repo.

edited comment to fix incorrect org name, slsa-framework vs. slsa

[kimsterv]

This looks good to me. @slsa-framework/slsa-steering-committee can you please review? Once we have consensus on approval, we can transfer this repo over.

[joshuagl]

Thank you for working on this @swinslow. Overall this looks like a good starting point to me.
I have a few clarifying questions and requested changes, a couple of minor nits we might want to fix (but could be handled as follow-on changes), and a few areas for clarification that we (the SLSA team) can handle.

Clarifications and requested changes:

• 4.1 of Governance suggests PR's are approved by a workstream. While we haven't fully formalised workstreams, I don't expect that would be standard practice. Rather, I expect PR approval to happen as it does today – by maintainers and the steering committee.
• 4.2 and 5 of Governance use 'approval of the project', but that term is never defined. Would that be a threshold of maintainers, a threshold of steering committee maintainers, both, something different?
• 4.2 of Contribution is confusing and may be missing some words?
• Our existing documents don't match the template, should we be updating things to match? Must we?

Nits (can be addressed as a follow-on set of changes):

• in Licenses, should we spell out the first mention of Apache-2.0 in full like the other two license mentions?
• Governance sections 4.3 & 4.4, and Contributing section 2 say "the Maintainer" but should, I think, be a plural "the Maintainers"

Suggested follow-on actions (for the SLSA team):

• Identify maintainers, explicitly list them, provide and publicly document a convenient alias (discussion group and/or GitHub team?) to address all maintainers to enable the documented appeals process
• Provide and publicly document an alias (discussion group and/or GitHub team) to address all steering committee members to enable the documented appeals process
• We should update Contributing:
  • section 4.1 to suggest using GitHub's draft PRs feature
  • throughout (especially 1 and 2.2) to recommend appropriate labels which are available on the SLSA repositories

[swinslow]

Thanks for the comments @joshuagl! A few thoughts on these:

4.1 of Governance suggests PR's are approved by a workstream. While we haven't fully formalised workstreams, I don't expect that would be standard practice. Rather, I expect PR approval to happen as it does today – by maintainers and the steering committee.

Understood. I was using "workstream" throughout the document in a somewhat informal sense, but yes, can certainly change this to reflect SLSA's practices.

Would you be good with that if 4.1 is updated to say "Pull requests will be merged upon Approval of the applicable Maintainers." ? Or we could say "...upon Approval of the applicable Maintainers and the Steering Committee", my only concern there is if you're expecting to require both Maintainer and SC sign-off for PRs.

4.2 and 5 of Governance use 'approval of the project', but that term is never defined. Would that be a threshold of maintainers, a threshold of steering committee maintainers, both, something different?

So, capital-A "Approval" for purposes of the Governance document is defined in Section 2.1. The intention is for it to be a consensus process as determined by the applicable Maintainers and/or Steering Committee acting in good faith. In other words, the Maintainers / SC will give good faith consideration as to whether consensus exists, based on the factors described in 2.1, and will document evidence of consensus; this process is what is meant by "Approval" throughout the document. And where there are disagreements with an Approval determination, 2.2 and 2.3 describe the appeals processes. Does that all make sense?

4.2 of Contribution is confusing and may be missing some words?

For this (and frankly much or all of the Contributing document), I think this can be set up however SLSA wants to operate and manage its contribution flow for the spec. The version that's here is part of the default that comes out of the box for the Community Specification model, but can certainly be changed.

For the "size label" I take that to mean the "small" / "medium" / "large" labels that some projects use. I don't see those labels in SLSA's repo, so would you prefer to just omit that reference?

Our existing documents don't match the template, should we be updating things to match? Must we?

It is not mandatory to use the template in that file for specs that use the Community Specification license (and certainly not mandatory on day 1!) The main advantage of moving towards that template over time would likely be if SLSA is aiming to seek recognition from ISO to become an ISO standard. ISO has very particular requirements for formatting specifications, which this template is structured to be more in alignment with. But no, it is not mandatory and particularly not if you aren't looking to apply with ISO.

For the two Nits -- great catches, I'll push an update for those. Let me know your thoughts on the other comments above. Thanks!

[swinslow]

Okay -- the nits should now be fixed in slsa-framework/governance#6. Will update the others as needed based on your thoughts from my comments above.

[joshuagl]

Thanks for the comments @joshuagl! A few thoughts on these:

4.1 of Governance suggests PR's are approved by a workstream. While we haven't fully formalised workstreams, I don't expect that would be standard practice. Rather, I expect PR approval to happen as it does today – by maintainers and the steering committee.

Understood. I was using "workstream" throughout the document in a somewhat informal sense, but yes, can certainly change this to reflect SLSA's practices.

Would you be good with that if 4.1 is updated to say "Pull requests will be merged upon Approval of the applicable Maintainers." ? Or we could say "...upon Approval of the applicable Maintainers and the Steering Committee", my only concern there is if you're expecting to require both Maintainer and SC sign-off for PRs.

"Pull requests will be merged upon Approval of the applicable Maintainers." feels right to me

4.2 and 5 of Governance use 'approval of the project', but that term is never defined. Would that be a threshold of maintainers, a threshold of steering committee maintainers, both, something different?

So, capital-A "Approval" for purposes of the Governance document is defined in Section 2.1. The intention is for it to be a consensus process as determined by the applicable Maintainers and/or Steering Committee acting in good faith. In other words, the Maintainers / SC will give good faith consideration as to whether consensus exists, based on the factors described in 2.1, and will document evidence of consensus; this process is what is meant by "Approval" throughout the document. And where there are disagreements with an Approval determination, 2.2 and 2.3 describe the appeals processes. Does that all make sense?

So it is. This is why we should try to avoid taking breaks mid-review. That all makes sense and matches my expectations, thanks Steve.

4.2 of Contribution is confusing and may be missing some words?

For this (and frankly much or all of the Contributing document), I think this can be set up however SLSA wants to operate and manage its contribution flow for the spec. The version that's here is part of the default that comes out of the box for the Community Specification model, but can certainly be changed.

For the "size label" I take that to mean the "small" / "medium" / "large" labels that some projects use. I don't see those labels in SLSA's repo, so would you prefer to just omit that reference?

Got it. I think we can just handle this on the SLSA side once the underlying repo is established.

Our existing documents don't match the template, should we be updating things to match? Must we?

It is not mandatory to use the template in that file for specs that use the Community Specification license (and certainly not mandatory on day 1!) The main advantage of moving towards that template over time would likely be if SLSA is aiming to seek recognition from ISO to become an ISO standard. ISO has very particular requirements for formatting specifications, which this template is structured to be more in alignment with. But no, it is not mandatory and particularly not if you aren't looking to apply with ISO.

Thanks for explaining, that matches my expectation but good to confirm.

For the two Nits -- great catches, I'll push an update for those. Let me know your thoughts on the other comments above. Thanks!

Your fixes in slsa-framework/governance#6 LGTM. Thank you.

[swinslow]

Great, thanks @joshuagl! I'll go ahead and update the 4.1 language for merging PRs momentarily.

[swinslow]

OK -- fixed in slsa-framework/governance#7

[joshuagl]

Thank you @swinslow.

Let's give some other members of @slsa-framework/slsa-steering-committee time to review.

[MarkLodato]

This looks really good. Thank you, @swinslow!

Two questions:

1. Regarding the Specification Development Process. Right now the specifications are embedded as part of our website. Every time we merge into main, it gets automatically published on the site. We nominally mark new version as "draft" and then remove "draft" when we think they're ready. But we often make tweaks to the spec to clarify things if they don't significantly change the meaning. Is that consistent with the Process, or do we need to alter how we do this, e.g. breaking apart the repo into the spec vs website and more formally publishing versions of the spec?

2. Once we adopt this, do we still need the Developer Certificate of Origin check that requires the Signed-off-by tag? IIUC that was a means to get explicit acceptance of the terms of the license, but it is a pain for contributors since GitHub doesn't add it automatically via web edites.

[joshuagl]

2. Once we adopt this, do we still need the Developer Certificate of Origin check that requires the Signed-off-by tag? IIUC that was a means to get explicit acceptance of the terms of the license, but it is a pain for contributors since GitHub doesn't add it automatically via web edites.

GitHub have a feature for this now. Project admins can mark DCO as required in the settings and the web UI will automatically fill it in https://github.blog/changelog/2022-06-08-admins-can-require-sign-off-on-web-based-commits/

[swinslow]

Thanks @MarkLodato!

For your first question, I think it's fine to continue to have it auto-publish to the site. I do think it would be helpful to have a mechanism which clearly indicates whether a particular version has been officially released as an "Approved" version of a spec -- essentially the same as tagging a specific commit as a particular released version of a software repo.

This is because the Community Spec License includes patent license terms that work somewhat differently for "Approved Specifications" (the versions that are tagged as approved releases) vs. those that are "Draft Specifications" (each other iteration). So it'll likely be useful to the community to clearly communicate "These here are the Approved Specification version releases" and that the others are Draft versions.

For your second question, DCO sign-off statements are not formally required by the Community Specification license and governance model. The terms in the Community Spec CLA indicate that the contributor accepts those terms "By making a Contribution to a repository in the slsa-framework GitHub organization..." That said, I would tend to still view the Signed-off-by statement as a best practice and still worth implementing. @joshuagl thanks for sharing the link about the new Github UI functionality -- I wasn't aware they had just rolled this out. That sounds extremely helpful for this purpose since I know this can be something of a pain at times otherwise.

[MarkLodato]

I'm good with adopting this in SLSA. Good to have more steering committee members sign off as well.

GitHub have a feature for this now. Project admins can mark DCO as required in the settings and the web UI will automatically fill it in https://github.blog/changelog/2022-06-08-admins-can-require-sign-off-on-web-based-commits/

Amazing! I just enabled it. Thanks for the tip! And thanks Steve for the info.

Regarding the first question, let's just keep that in mind for the future.

[trishankatdatadog]

If the OpenSSF recommends the Community Specification License, then I am all for it. No major objections!

[swinslow]

Chatting with @kimsterv, sounds like we're all set to move this over! I've migrated the repo to https://github.com/slsa-framework/governance.

Will go ahead and close this issue. Thanks all for your help in reviewing this!

[joshuagl]

FYI for folks following along, I've filed Issues on the new slsa-framework/governance repository for the follow-on items I suggested:

• Update contributing to match established SLSA process governance#8
• Document maintainers governance#9
• Document communication methods for appeals process governance#10