Skip to content

Proposal: working group for reference types #103

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
merged 4 commits into from
Dec 15, 2021
Merged

Proposal: working group for reference types #103

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f973869
Proposal: working group for reference types
SteveLasker Nov 18, 2021
fddaf15
Changing sponsors to stakeholders, per PR feedback
SteveLasker Nov 22, 2021
54eb9b7
Incorporate typo, linting feedback
SteveLasker Dec 1, 2021
0e68daa
Incorporate pr feedback around extending existing or creating a new m…
SteveLasker Dec 1, 2021
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
86 changes: 86 additions & 0 deletions proposals/wg-reference-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Working Group Proposal: Reference Types

Proposal created from [OCI WG template](https://github.com/opencontainers/tob/blob/master/WG-TEMPLATE.md).

Proposal copied from [Proposal: Working Group for Reference Types #96](https://github.com/opencontainers/tob/issues/96)

## Reference Types OCI Working Group - Governance Charter

This document describes the basic governance principles for the Reference Types Working Group (the “WG”).

The WG operates as an OCI Working Group under the [Open Container Initiative (OCI) Charter](https://github.com/opencontainers/tob/blob/master/CHARTER.md), which describes the responsibilities of the OCI Technical Oversight Board (the "TOB”). The WG is established by the TOB as an OCI Working Group pursuant to the OCI Charter. Accordingly, the WG will operate in accordance with the OCI Charter and OCI's other policies and procedures, supplemented by the details below.

## Purpose

As cloud native development continues to grow, there is increased interest in evolving registries to natively store, discover, and pull a graph of content associated with specific container images in a registry. Use cases for said associated artifacts include but are not limited to Software Bill of Materials (SBoM), security scan results, and signing. Having a native way to store and discover artifacts associated with other artifacts enables end-users to answer the question of: “What SBOMs or signatures are associated with this container image?”

## Scope

Copy link
Contributor

Choose a reason for hiding this comment

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

Are these bullets intended to be a flat list?

Copy link

Choose a reason for hiding this comment

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

They are supposed to be indented from the second bullet on.

* Define and deliver the capability to store, discover, and pull a graph of artifacts associated with a specific artifacts to OCI distribution compliant registries. These set of capabilities has been commonly known as "reference types" or "references".
* Define supported use cases
* Document impact to existing user-facing tools and registries
* Define the method for creating, distributing, and discovering referenced objects
* Document user expectations for promoting an artifact between registries with its references
* Document onboarding process for registries and user-facing tools to adopt reference types
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* Document onboarding process for registries and user-facing tools to adopt reference types
* Document path to adoption for registries and other implementations

* Defined expectations for artifact reference lifecycle management
* Deliver a reference implementation of the reference types proposal
Copy link
Member

Choose a reason for hiding this comment

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

Just a note per the Governance section and the relevant parts of the Charter: a new reference implementation will require a new TOB vote at the time it is ready for it to become an OCI Project.

Copy link
Contributor

Choose a reason for hiding this comment

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

I'd probably drop this or downgrade to a proof of concept. It's going to be confusing to talk about the reference reference implementation.


## Out of Scope

* Identified out of scope items will be listed here as WG progresses


## Intended work product

* Referrers API specification that provides the ability to discover references to existing container images. These include listing signatures, SBoMs, security scan results that refer to the digest of a manifest. The referrers API specification will sit within or along side the Distribution specification.
* Identify, and document the pros and cons for versioning the existing manifests, compared with creating a new manifest to support reference types.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* Identify, and document the pros and cons for versioning the existing manifests, compared with creating a new manifest to support reference types.
* Proposal to extend existing manifests or create a new manifest to support reference types.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

To address any of the existing manifests, we do need to address how these would be versioned. So, I propose we leave this as stated as the updated wording does change the process.

Copy link
Contributor

Choose a reason for hiding this comment

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

Just documenting the pros and cons doesn't feel like a great work product. Having a concrete proposal for existing manifests feels like a prerequisite for doing this analysis, so if that's implied by what you have here, that's fine with me.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ahh, I see, so it's a merger of the two.
What I didn't want to lose was the versioning analysis, and just jump into debating solutions. I've merged both concepts.


## Proposed Owners
* Lachlan Evenson (@lachie83)
* Justin Cormack (@justincormack)
* Michael Brown (@michaelb990)
* Derek McGowan (@dmcgowan)
* Jon Johnson (@jonjohnsonjr)

## Sponsors

* Microsoft
* AWS
* Docker

Copy link
Contributor Author

Choose a reason for hiding this comment

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

From #96, there's an open clarification if Google will be a sponsor.

Copy link
Member

Choose a reason for hiding this comment

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

If there's an open question we should resolve that before voting.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@jonjohnsonjr, can you clarify if Google will be a sponsor?

Copy link

Choose a reason for hiding this comment

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

Would it effect the vote either way? I'm no longer at Google, but if I remember the process correctly, getting an actual answer here will be very annoying and time consuming.

Copy link
Member

Choose a reason for hiding this comment

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

I'd rather not start the voting process if we expect the thing we're voting on to change. If @SteveLasker wants to drop the question and we vote on the proposal as-is that would be fine to me.

Copy link

Choose a reason for hiding this comment

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

I'm happy to add cosign to the list if that helps. I'm also happy to leave it off if that helps get the vote started faster.

Copy link
Contributor

Choose a reason for hiding this comment

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

If it's a point of contention, I suggest we just remove any notion of "corporations" as sponsors as the work done under this WG has been discussed at length without any specific need for guidance/sponsorship from the employers/entities themselves.

I understand initially the list was denoting companies which a specific interest in this work and had people involved for that purpose, but I think we've made it clear this is an open WG that will hopefully involve input from any registry operator, open source registry implementation, clients, etc.

Delaying at this point to formalize or determine a list of company names seems unnecessary given we have struggled for months to get this rolling and are all fully aware of the work that needs to be accomplished collaboratively no matter who is listed in this proposal. My intent was to hopefully involve a good cross-section of people, which should be much larger than just the "owners", but the owners list will help shepherd the discussion, status, and progress of the group and, in my opinion, is a good cross-section of people with OCI history, registry open source projects, operating registries, and so on.

Copy link
Member

Choose a reason for hiding this comment

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

exactly what phil said. While I'm sure that "sponsor" equates to "my employer allows me to allocate time to this, and is interested in seeing this completed", it would be tedious to tease that out before getting this in.
I'd rather just see GH handles of the stakeholders that are going to see this through to completion.

Copy link
Member

Choose a reason for hiding this comment

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

can't we just change this "Sponsor" to "Stakeholder" and move on with it?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Changed sponsors to stakeholders.
With this change, are there any other changes before moving to the vote?

## Related issues/PRs

* https://github.com/opencontainers/tob/issues/96
* https://github.com/opencontainers/artifacts/pull/27
* https://github.com/opencontainers/artifacts/pull/29
* https://github.com/opencontainers/artifacts/pull/37
* https://github.com/opencontainers/image-spec/issues/827
* https://github.com/opencontainers/image-spec/pull/828
* https://github.com/oras-project/artifacts-spec/
Copy link
Member

Choose a reason for hiding this comment

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

Just a note here that this repository is not itself an OCI Project even though many of the people working on it are also involved in OCI (and in this proposed WG).


## Governance

* **Working Group**:
* The TOB is establishing the WG as an OCI Working Group, pursuant to [section 6(p)](https://github.com/opencontainers/tob/blob/master/CHARTER.md#6-technical-oversight-board-tob) of the OCI Charter.
* **Owners**:
* The WG proposal to the TOB will specify one or more initial "owners" of the WG.
* The current owners will be listed in the [OCI Working Group documentation](https://github.com/opencontainers/tob/blob/master/WG-INFO.md).
* The owners shall be responsible for:
* scheduling regular meetings of the WG community;
* facilitating open discussion among WG community participants;
* coordinating and managing the development of the WG work product and outputs;
* recording decisions that are reached by the WG community; and
* keeping the TOB regularly informed about the status of the WG’s efforts, including when the WG has readied the work product and outputs for TOB approval.
* **Maintainers**:
* If the WG owners request the TOB to approve a draft specification as a released OCI Specification, the request shall include a list of proposed "maintainers" of the OCI Specification.
* The current maintainers will be listed in the [OCI Working Group documentation](https://github.com/opencontainers/tob/blob/master/WG-INFO.md).
* The maintainers shall be responsible for continuing the work of overseeing updates, improvements and changes to a released OCI Specification on an ongoing basis.
* **Meetings**:
* Meetings of the WG shall be open to the public.
* Participants in the meetings shall comply with the [OCI Code of Conduct](https://github.com/opencontainers/.github/blob/master/CODE_OF_CONDUCT.md) and all other policies of OCI and The Linux Foundation.
* **TOB Approval**:
* The WG shall operate pursuant to the procedures set forth in [section 6(p)](https://github.com/opencontainers/tob/blob/master/CHARTER.md#6-technical-oversight-board-tob) of the OCI Charter, with regards to obtaining TOB approval for initial release of the work product and outputs as an OCI Specification or other OCI Project, and for subsequent maintenance activities thereafter.
* **Amendments**:
* The owners of the WG may from time to time propose to the TOB (1) amendments to this WG Governance Document, and/or (2) changes to the composition of the owners or maintainers of the WG.
* As set forth in the OCI Charter, the TOB may, in its discretion by a two-thirds vote, approve or reject the requested amendments or changes.
* As set forth in the OCI Charter, the TOB may also disband the WG by a two-thirds vote.