Add README link to Guidelines for Artifact Usage

[jdolitsky]

@opencontainers/artifacts-maintainers PTAL

[mikebrow]

if we need to drop one or any of the charter items.. like the clearing house concept.. let's do it at the tob first.

IMO there is still a need for a clearing house comprising artifact types. Even if all we do is link to them I think there is value in having known standards for certain artifact types esp. those that are essentially extensions of OCI expected to be supported by registries/clients and platforms implementing/using the OCI specs.

[jdolitsky]

I followed your provided link and it's missing much of what this project was chartered to provide.

if thats the case, then we should submit a PR to image-spec to modify that section to include any missing topics that you allude to. IMO this change is necessary to turn people away from this repository and into image-spec/distribution-spec where these conversations are continuing.

[mikebrow]

I followed your provided link and it's missing much of what this project was chartered to provide.

if thats the case, then we should submit a PR to image-spec to modify that section to include any missing topics that you allude to. IMO this change is necessary to turn people away from this repository and into image-spec/distribution-spec where these conversations are continuing.

... I see this cross link to the tob issue above.. https://github.com/opencontainers/tob/issues/126, guessing the tob was busy today :)

No doubt changes are nec. happy to help.

Suggest we move / edit the charter items via tob action and while that's going on lets make changes here in the artifacts readme that reflect where the RC guidance can be found now. Hot linking into the middle of the image spec works but could be confusing without some context. I see that the image spec content has a hot link over to the distribution referrers api. so that's good, but again it's a link into the middle of a RC spec with minimal context.

I think if we start at the root of image/dist repo readme's and add some context about the role of artifacts to those respective repos (note there is no mention of artifacts in the image spec readme and only an off comment out of context mention in dist :-)

Probably need some high level pictures for how this is expected to work maybe we could do a blog and link to that? Or add a separate non spec doc for intro level guidance with links into the appropriate areas of the specs for detail.

Thoughts? will ping on slack cheers..

[sudo-bmitch]

1. artifact authors - [guidance for authoring new artifact types.][artifact-authors]

The guidance here for artifact authors does not match what image spec provides, and does not cover situations where the artifact type does not match the config blob content, which is why we had to add the artifactType field and scratch descriptor. Having outdated guidance is confusing to the community.

1. registry operators and vendors - guidance for how operators and vendors can support new artifact types, including how they can opt-in or out of well known artifact types. ... provide context on how new media-types can be used, and how media-types can be associated with a type of artifact.

The changes to distribution-spec exclude the option to opt in, registries are only allowed to opt out of specific artifactType values that they would list. Artifact types that are unknown to the registry must be accepted. If a link for that is needed, it would probably be to distribution-spec under pushing manifests.

1. clearing house for well known artifacts - artifact authors can submit their artifact definitions, providing registry operators a list by which they can easily support

This is nice for showing adoption, but less useful for registries to test since there's a requirement to accept any unknown artifact type, so they can't just verify they support well known artifact types.

If we want to show a list for recognition, artifact producers list themselves as an implementation of image-spec with a PR there.

[mikebrow]

1. artifact authors - [guidance for authoring new artifact types.][artifact-authors]

The guidance here for artifact authors does not match what image spec provides, and does not cover situations where the artifact type does not match the config blob content, which is why we had to add the artifactType field and scratch descriptor. Having outdated guidance is confusing to the community.

1. registry operators and vendors - guidance for how operators and vendors can support new artifact types, including how they can opt-in or out of well known artifact types. ... provide context on how new media-types can be used, and how media-types can be associated with a type of artifact.

The changes to distribution-spec exclude the option to opt in, registries are only allowed to opt out of specific artifactType values that they would list. Artifact types that are unknown to the registry must be accepted. If a link for that is needed, it would probably be to distribution-spec under pushing manifests.

1. clearing house for well known artifacts - artifact authors can submit their artifact definitions, providing registry operators a list by which they can easily support

This is nice for showing adoption, but less useful for registries to test since there's a requirement to accept any unknown artifact type, so they can't just verify they support well known artifact types.

If we want to show a list for recognition, artifact producers list themselves as an implementation of image-spec with a PR there.

I think we are in violent agreement :-)

[mikebrow]

see carry in #68

[SteveLasker]

Closing, as #68 starts the process of documenting updated status, as opposed to simply blanking the content

[jdolitsky]