From 2688d93b4f076791a135210b3cf9c8dbeafa01b6 Mon Sep 17 00:00:00 2001 From: Xiaoxuan Wang Date: Tue, 23 Apr 2024 07:59:02 +0000 Subject: [PATCH 1/4] doc: document PackManifestOptions to make PackManifest reproducible Signed-off-by: Xiaoxuan Wang --- pack.go | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/pack.go b/pack.go index 1b995612..c9d04dba 100644 --- a/pack.go +++ b/pack.go @@ -93,7 +93,9 @@ type PackManifestOptions struct { // Layers is the layers of the manifest. Layers []ocispec.Descriptor - // ManifestAnnotations is the annotation map of the manifest. + // ManifestAnnotations is the annotation map of the manifest. Set + // "org.opencontainers.image.created" with a value to make PackManifest + // reproducible. ManifestAnnotations map[string]string // ConfigDescriptor is a pointer to the descriptor of the config blob. @@ -126,6 +128,11 @@ var mediaTypeRegexp = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9!#$&-^_.+]{0,126 // // artifactType and opts.ConfigDescriptor.MediaType MUST comply with RFC 6838. // +// Each time when PackManifest is called, it generates a new time stamp in the +// manifest annotations with the key "org.opencontainers.image.created". To make +// PackManifest reproducible, set "org.opencontainers.image.created" with a value +// in opts.ManifestAnnotations. +// // If succeeded, returns a descriptor of the packed manifest. func PackManifest(ctx context.Context, pusher content.Pusher, packManifestVersion PackManifestVersion, artifactType string, opts PackManifestOptions) (ocispec.Descriptor, error) { switch packManifestVersion { From 436840542dc0da865ee484db7536b7ff50167951 Mon Sep 17 00:00:00 2001 From: Xiaoxuan Wang Date: Mon, 6 May 2024 07:18:10 +0000 Subject: [PATCH 2/4] resolved comments Signed-off-by: Xiaoxuan Wang --- example_pack_test.go | 6 ++++-- pack.go | 16 ++++++++-------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/example_pack_test.go b/example_pack_test.go index aff41d9b..baa95e71 100644 --- a/example_pack_test.go +++ b/example_pack_test.go @@ -35,7 +35,8 @@ func ExamplePackManifest_imageV11() { opts := oras.PackManifestOptions{ ManifestAnnotations: map[string]string{ // this timestamp will be automatically generated if not specified - // use a fixed value here in order to test the output + // use a fixed value here in order to test the output and make the + // pack reproducible. ocispec.AnnotationCreated: "2000-01-01T00:00:00Z", }, } @@ -71,7 +72,8 @@ func ExamplePackManifest_imageV10() { opts := oras.PackManifestOptions{ ManifestAnnotations: map[string]string{ // this timestamp will be automatically generated if not specified - // use a fixed value here in order to test the output + // use a fixed value here in order to test the output and make the + // pack reproducible. ocispec.AnnotationCreated: "2000-01-01T00:00:00Z", }, } diff --git a/pack.go b/pack.go index c9d04dba..969dc3ac 100644 --- a/pack.go +++ b/pack.go @@ -48,8 +48,8 @@ const ( var ( // ErrInvalidDateTimeFormat is returned by [Pack] and [PackManifest] when - // AnnotationArtifactCreated or AnnotationCreated is provided, but its value - // is not in RFC 3339 format. + // "org.opencontainers.artifact.created" or "org.opencontainers.image.created" + // is provided, but its value is not in RFC 3339 format. // Reference: https://www.rfc-editor.org/rfc/rfc3339#section-5.6 ErrInvalidDateTimeFormat = errors.New("invalid date and time format") @@ -93,9 +93,9 @@ type PackManifestOptions struct { // Layers is the layers of the manifest. Layers []ocispec.Descriptor - // ManifestAnnotations is the annotation map of the manifest. Set - // "org.opencontainers.image.created" with a value to make PackManifest - // reproducible. + // ManifestAnnotations is the annotation map of the manifest. In order to + // make PackManifest reproducible, set the key ocispec.AnnotationCreated to + // a fixed value. The value must conform to RFC 3339. ManifestAnnotations map[string]string // ConfigDescriptor is a pointer to the descriptor of the config blob. @@ -129,9 +129,9 @@ var mediaTypeRegexp = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9!#$&-^_.+]{0,126 // artifactType and opts.ConfigDescriptor.MediaType MUST comply with RFC 6838. // // Each time when PackManifest is called, it generates a new time stamp in the -// manifest annotations with the key "org.opencontainers.image.created". To make -// PackManifest reproducible, set "org.opencontainers.image.created" with a value -// in opts.ManifestAnnotations. +// manifest annotations with the key ocispec.AnnotationCreated. To make +// PackManifest reproducible, set the key ocispec.AnnotationCreated to a fixed value +// in opts.ManifestAnnotations. The value MUST conform to RFC 3339. // // If succeeded, returns a descriptor of the packed manifest. func PackManifest(ctx context.Context, pusher content.Pusher, packManifestVersion PackManifestVersion, artifactType string, opts PackManifestOptions) (ocispec.Descriptor, error) { From 06bbe803dc263828db4ca4edc05184beebfa9e03 Mon Sep 17 00:00:00 2001 From: Xiaoxuan Wang Date: Tue, 7 May 2024 06:26:39 +0000 Subject: [PATCH 3/4] resolved comment Signed-off-by: Xiaoxuan Wang --- example_pack_test.go | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/example_pack_test.go b/example_pack_test.go index baa95e71..169e0911 100644 --- a/example_pack_test.go +++ b/example_pack_test.go @@ -35,8 +35,7 @@ func ExamplePackManifest_imageV11() { opts := oras.PackManifestOptions{ ManifestAnnotations: map[string]string{ // this timestamp will be automatically generated if not specified - // use a fixed value here in order to test the output and make the - // pack reproducible. + // use a fixed value here to make the pack result reproducible ocispec.AnnotationCreated: "2000-01-01T00:00:00Z", }, } @@ -72,8 +71,7 @@ func ExamplePackManifest_imageV10() { opts := oras.PackManifestOptions{ ManifestAnnotations: map[string]string{ // this timestamp will be automatically generated if not specified - // use a fixed value here in order to test the output and make the - // pack reproducible. + // use a fixed value here to make the pack result reproducible ocispec.AnnotationCreated: "2000-01-01T00:00:00Z", }, } From 961075dca41fd5e24ab4f8e18ce187ff9cfe8583 Mon Sep 17 00:00:00 2001 From: Xiaoxuan Wang Date: Tue, 7 May 2024 12:01:37 +0000 Subject: [PATCH 4/4] resolved comments Signed-off-by: Xiaoxuan Wang --- example_pack_test.go | 4 ++-- pack.go | 14 ++++++++------ 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/example_pack_test.go b/example_pack_test.go index 169e0911..9adf8fae 100644 --- a/example_pack_test.go +++ b/example_pack_test.go @@ -34,7 +34,7 @@ func ExamplePackManifest_imageV11() { // 1. Set optional parameters opts := oras.PackManifestOptions{ ManifestAnnotations: map[string]string{ - // this timestamp will be automatically generated if not specified + // this time stamp will be automatically generated if not specified // use a fixed value here to make the pack result reproducible ocispec.AnnotationCreated: "2000-01-01T00:00:00Z", }, @@ -70,7 +70,7 @@ func ExamplePackManifest_imageV10() { // 1. Set optional parameters opts := oras.PackManifestOptions{ ManifestAnnotations: map[string]string{ - // this timestamp will be automatically generated if not specified + // this time stamp will be automatically generated if not specified // use a fixed value here to make the pack result reproducible ocispec.AnnotationCreated: "2000-01-01T00:00:00Z", }, diff --git a/pack.go b/pack.go index 969dc3ac..d67388a7 100644 --- a/pack.go +++ b/pack.go @@ -94,8 +94,9 @@ type PackManifestOptions struct { Layers []ocispec.Descriptor // ManifestAnnotations is the annotation map of the manifest. In order to - // make PackManifest reproducible, set the key ocispec.AnnotationCreated to - // a fixed value. The value must conform to RFC 3339. + // make [PackManifest] reproducible, set the key ocispec.AnnotationCreated + // (i.e. "org.opencontainers.image.created") to a fixed value. The value + // must conform to RFC 3339. ManifestAnnotations map[string]string // ConfigDescriptor is a pointer to the descriptor of the config blob. @@ -128,10 +129,11 @@ var mediaTypeRegexp = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9!#$&-^_.+]{0,126 // // artifactType and opts.ConfigDescriptor.MediaType MUST comply with RFC 6838. // -// Each time when PackManifest is called, it generates a new time stamp in the -// manifest annotations with the key ocispec.AnnotationCreated. To make -// PackManifest reproducible, set the key ocispec.AnnotationCreated to a fixed value -// in opts.ManifestAnnotations. The value MUST conform to RFC 3339. +// Each time when PackManifest is called, if a time stamp is not specified, a new time +// stamp is generated in the manifest annotations with the key ocispec.AnnotationCreated +// (i.e. "org.opencontainers.image.created"). To make [PackManifest] reproducible, +// set the key ocispec.AnnotationCreated to a fixed value in +// opts.ManifestAnnotations. The value MUST conform to RFC 3339. // // If succeeded, returns a descriptor of the packed manifest. func PackManifest(ctx context.Context, pusher content.Pusher, packManifestVersion PackManifestVersion, artifactType string, opts PackManifestOptions) (ocispec.Descriptor, error) {