Skip to content
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

Jump to bottom

[tracker] revamp the spec #126

Closed
11 of 14 tasks
vbatts opened this issue Apr 1, 2020 · 3 comments
Closed
11 of 14 tasks

[tracker] revamp the spec #126

vbatts opened this issue Apr 1, 2020 · 3 comments
Milestone
v1.0.0-rc2

Comments

@vbatts
Copy link
Member

vbatts commented Apr 1, 2020 •
edited by jdolitsky

Tracker for reorganizing the spec (started from #125 discussion)
As of commit 38956df:

  • TOC
  • murder the changes.md file
  • introduction
  • historical context (moved to ./history.md)
  • terms / glossary
  • conformance categories
  • endpoints (nitty gritty)
  • add appendix
  • describe relationship to OCI images
  • uses cases should link to workflows
  • "image" -> "artifact"
  • remove rules/requirements specific to images (blobs before configs etc)
  • finalize HTTP status codes
  • address Regular expressions missing for name, reference, etc. #183

the idea being that these are mergable chunks of PRs,
For readers of the spec, the spec is organized according to the nature of the reviewers (general information, slightly more detail, and registry/tool implementors).
@vbatts vbatts mentioned this issue Apr 1, 2020
Closed
vbatts added a commit to vbatts/oci-distribution-spec that referenced this issue Apr 1, 2020
@vbatts
changes.md: no longer needed
7889f55 
Ref opencontainers#126

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
@vbatts vbatts mentioned this issue Apr 1, 2020
Merged
@jdolitsky
Copy link
Member

For changes related to spec.md, does it make sense for us to open up a new staging branch like "rewrite" ? Then once all these boxes are checked, do a big PR from rewrrite->master with a bunch of changes that the maintainers have already agreed upon?

The alternative I see is making a new glossary.md etc on master which would later be deleted. Thoughts?

@vbatts vbatts mentioned this issue Apr 1, 2020
Closed
@mikebrow
Copy link
Member

mikebrow commented Apr 1, 2020 •
edited

still to do on murder the changes.md item... remove or rewrite the ## changes section https://github.com/opencontainers/distribution-spec/blame/master/spec.md#L131

@pmengelbert pmengelbert mentioned this issue Apr 6, 2020
Closed
@jdolitsky jdolitsky mentioned this issue May 6, 2020
Merged
@jzelinskie jzelinskie added this to the v1.0.0-rc1 milestone May 6, 2020
jdolitsky added a commit to bloodorangeio/distribution-spec that referenced this issue May 20, 2020
@jdolitsky
Spec reorganization pt 1
e90bebe 
Related to opencontainers#126

The following sections have been removed:
- Changes
- Historial Context (already in reorg)
- Overview / Listing Repositories (unused catalog API)

The following sections have been moved into commented reorg:
- Notational Conventions ---> Definitions / Document Language
- Overview / Errors ---> HTTP API / Error Codes
- Overview / API Version Check ---> Conformance / Workflow Categories / Pull
- Overview / Pulling An Image ---> Conformance / Workflow Categories / Pull
- Overview / Pushing An Image ---> Conformance / Workflow Categories / Push
- Overview / Listing Image Tags ---> Conformance / Workflow Categories / Content Discovery
- Overview / Deleting an Image ---> Conformance / Workflow Categories / Content Management
- Detail / Errors ---> HTTP API / Error Codes

Signed-off-by: Josh Dolitsky <393494+jdolitsky@users.noreply.github.com>
@jdolitsky jdolitsky mentioned this issue May 20, 2020
Closed
jdolitsky added a commit to bloodorangeio/distribution-spec that referenced this issue May 20, 2020
@jdolitsky
Spec reorganization pt 1
e6a43cc 
Related to opencontainers#126

The following sections have been removed:
- Changes
- Historical Context (already in reorg)
- Overview / Listing Repositories (unused catalog API)

The following sections have been moved into commented reorg:
- Notational Conventions ---> Definitions / Document Language
- Overview / Errors ---> HTTP API / Error Codes
- Overview / API Version Check ---> Conformance / Workflow Categories / Pull
- Overview / Pulling An Image ---> Conformance / Workflow Categories / Pull
- Overview / Pushing An Image ---> Conformance / Workflow Categories / Push
- Overview / Listing Image Tags ---> Conformance / Workflow Categories / Content Discovery
- Overview / Deleting an Image ---> Conformance / Workflow Categories / Content Management
- Detail / Errors ---> HTTP API / Error Codes

Signed-off-by: Josh Dolitsky <393494+jdolitsky@users.noreply.github.com>
@jdolitsky jdolitsky mentioned this issue Jun 10, 2020
Closed
14 tasks
jdolitsky added a commit that referenced this issue Jul 29, 2020
@pmengelbert @jdolitsky
mini update 6: describe pull workflow (#166)
f8d87fb 
* Spec reorganization pt 1

Related to #126

The following sections have been removed:
- Changes
- Historical Context (already in reorg)
- Overview / Listing Repositories (unused catalog API)

The following sections have been moved into commented reorg:
- Notational Conventions ---> Definitions / Document Language
- Overview / Errors ---> HTTP API / Error Codes
- Overview / API Version Check ---> Conformance / Workflow Categories / Pull
- Overview / Pulling An Image ---> Conformance / Workflow Categories / Pull
- Overview / Pushing An Image ---> Conformance / Workflow Categories / Push
- Overview / Listing Image Tags ---> Conformance / Workflow Categories / Content Discovery
- Overview / Deleting an Image ---> Conformance / Workflow Categories / Content Management
- Detail / Errors ---> HTTP API / Error Codes

Signed-off-by: Josh Dolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 4: fill in definitions section

Fill in the definitions section, introducing several
terms and defintions which will serve as reference for
the rest of the document.

Also moved the "notational conventions" section into
this section, removing any language that seemed
unnecessary or related to compliance (which will be
covered in the conformance section).

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 5: fill in conformance section (sans workflows)

Fill in conformance section, adding minimum requirements
stating that all compliant registries must at least support Pull.

Added a section regarding certification, linking to the
opencontainers/oci-conformance repo.

For the workflow sections, intentionally left blank, and will
be added in a follow-up PR.

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* Describe the pull workflow

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

* update digest and content definitions

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* add notational conventions section

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update description of content management

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 2: new table of contents

This is a new table of contents for the spec, designed to
add simplicity and organization.

Existing content will later be moved into one of these sections,
or removed entirely if considered superfluous.

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* remove top-level defintions section

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 3: fill in overview section

Fill in the overview section, including new introduction
referring to "content" (vs. just container images).

Move historical context section underneath overview.

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 4: fill in definitions section

Fill in the definitions section, introducing several
terms and defintions which will serve as reference for
the rest of the document.

Also moved the "notational conventions" section into
this section, removing any language that seemed
unnecessary or related to compliance (which will be
covered in the conformance section).

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update digest and content definitions

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 5: fill in conformance section (sans workflows)

Fill in conformance section, adding minimum requirements
stating that all compliant registries must at least support Pull.

Added a section regarding certification, linking to the
opencontainers/oci-conformance repo.

For the workflow sections, intentionally left blank, and will
be added in a follow-up PR.

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* mini update 5: fill in conformance section (sans workflows)

Fill in conformance section, adding minimum requirements
stating that all compliant registries must at least support Pull.

Added a section regarding certification, linking to the
opencontainers/oci-conformance repo.

For the workflow sections, intentionally left blank, and will
be added in a follow-up PR.

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* Describe the pull workflow

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

* update definitions based on github review

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* add addressable by a digest

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* replace the with a

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* replace metadata with config

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* add and associated blob

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update digest definition

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* a cryptographic hash vs. the

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* update based on PR comments

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* capital MUST

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* merge conflicts

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* manual rebase on reorg

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

* Adjust grammar

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Co-authored-by: Josh Dolitsky <393494+jdolitsky@users.noreply.github.com>
@jdolitsky jdolitsky mentioned this issue Sep 11, 2020
Closed
@jdolitsky jdolitsky mentioned this issue Sep 22, 2020
Merged
7 tasks
@mikebrow mikebrow modified the milestones: v1.0.0-rc1, v1.0.0-rc2 Oct 7, 2020
@pmengelbert pmengelbert mentioned this issue Oct 28, 2020
Merged
@jdolitsky
Copy link
Member

Resolved by #206

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
v1.0.0-rc2
Development

No branches or pull requests
4 participants
@vbatts @jzelinskie @jdolitsky @mikebrow