search

opencontainers / distribution-spec

OCI Distribution Specification
https://opencontainers.org
Apache License 2.0
781 stars 201 forks source link

Historical curiosity: Why did we delete half the spec, again? #443

Open jonjohnsonjr opened 1 year ago

jonjohnsonjr commented 1 year ago

I cannot for the life of me remember why this happened: https://github.com/opencontainers/distribution-spec/commit/c90b0f145ac6bc09d2636ee214486ac333edc284

There is a ton of stuff missing from distribution-spec, still.

vbatts commented 1 year ago

It did improve readability. The spec carried over from Docker had a lot of generated cruft. But it was a huge endeavor. I wouldn't doubt that things were missed. What particularly are you finding missing?

corhere commented 11 months ago

I, for one, am missing the historical context and decision making behind many of the nontrivial spec changes, such as

- Actionable failure conditions, covered in detail in their relevant sections, are reported as part of 4xx responses, in a json response body.
- One or more errors will be returned in the following format:
+ A `4XX` response code from the registry MAY return a body in any format. If the response body is in JSON format, it MUST
+ have the following format:

and how Content-Type: application/octet-stream became a required request header when PATCHing blobs. Before #178 the spec included a table of headers and parameters that SHOULD be included, which did not include the Content-Type header. The Content-Type header was only mentioned in an illustrative example.

Also:

At one point we deprecated catalog, but I can't seem to find reference to it anywhere after #178

jonjohnsonjr commented 11 months ago

What particularly are you finding missing?

I can't find any reference to the pagination mechanism for tag listing. I think this got dropped when catalog was [re]moved?

It makes a lot more sense to me now that folks had started inventing new pagination mechanisms for the referrers API: they didn't have the existing mechanism to copy!

sudo-bmitch commented 11 months ago

We also define a chunked upload, but not the streaming upload for blobs.

vbatts commented 11 months ago

On 21/07/23 07:41 -0700, Jon Johnson wrote:

I can't find any reference to the pagination mechanism for tag listing. I think this got dropped when catalog was [re]moved?

open a PR to add it back! pagination was useful, and if folks have already implemented it, then we ought not introduce new and different ways of doing it.