From 9ac8f92d3f0782e9d344d21c7a948d5c799c8323 Mon Sep 17 00:00:00 2001 From: Brandon Mitchell Date: Fri, 4 Aug 2023 16:26:56 -0400 Subject: [PATCH 1/2] Quote lint-md wildcard expression This avoids a potential foot gun, where a future md file in a sub directory would match the wildcard in the shell, and not pass the expression to the linter. Signed-off-by: Brandon Mitchell --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index a5075d9cf..d69818c55 100644 --- a/Makefile +++ b/Makefile @@ -95,7 +95,7 @@ lint-go: .install.lint ## lint check of Go files using golangci-lint .PHONY: lint-md lint-md: ## Run linting for markdown docker run --rm -v "$(PWD):/workdir:ro" docker.io/davidanson/markdownlint-cli2:$(MARKDOWN_LINT_VER) \ - **/*.md "#vendor" + "**/*.md" "#vendor" .PHONY: test test: ## run the unit tests From 72b3fb09b2a98c5ce3ca89fa7cd7c027011b4d29 Mon Sep 17 00:00:00 2001 From: Brandon Mitchell Date: Fri, 4 Aug 2023 15:44:27 -0400 Subject: [PATCH 2/2] Provide a decision tree for artifacts Signed-off-by: Brandon Mitchell --- artifacts-guidance.md | 4 ++-- manifest.md | 8 ++++++++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/artifacts-guidance.md b/artifacts-guidance.md index 2af485c0d..2055facb2 100644 --- a/artifacts-guidance.md +++ b/artifacts-guidance.md @@ -1,5 +1,5 @@ # Guidance for Artifacts Authors Content other than OCI container images MAY be packaged using the image manifest. -When this is done, the `config.mediaType` value MUST be set to a value specific to the artifact type or the [empty value](manifest.md#guidance-for-an-empty-descriptor). -Additional details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage). +When this is done, the `config.mediaType` value will not be a known OCI image config [media type](media-types.md). +Implementation details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage). diff --git a/manifest.md b/manifest.md index de32bc23a..589426250 100644 --- a/manifest.md +++ b/manifest.md @@ -175,6 +175,14 @@ If the `config.mediaType` is set to the empty value, the `artifactType` MUST be If the artifact does not need layers, a single layer SHOULD be included with a non-zero size. The suggested content for an unused `layers` array is the [empty descriptor](#guidance-for-an-empty-descriptor). +The design of the artifact depends on what content is being packaged with the artifact. +The decision tree below MAY be used to structure your artifact: + +1. Does the artifact consist of at least one file or blob? If yes, continue to 2. If no, specify the `artifactType`, and set the `config` and a single `layers` element to the empty descriptor value. +2. Does the artifact have additional JSON formatted metadata as configuration? If yes, continue to 3. If no, specify the `artifactType`, include the artifact in the `layers`, and set `config` to the empty descriptor value. +3. Does the artifact require a different `artifactType` from the `config.mediaType`, to support multiple configuration formats or versions for the same artifact tooling? If yes, continue to 4. If no, specify the `config` with the metadata, include the artifact in the `layers`, but do not set the `artifactType`. +4. Specify the `artifactType` to a common value for your artifact tooling, specify the `config` with the metadata for this artifact, and include the artifact in the `layers`. + Here is an example manifest for a typical artifact: ```json,title=Artifact%20with%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson