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

docs: document PackManifestOptions to make PackManifest reproducible #749

Merged
merged 4 commits into from
May 20, 2024
Merged

docs: document PackManifestOptions to make PackManifest reproducible #749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2688d93
doc: document PackManifestOptions to make PackManifest reproducible
wangxiaoxuan273 Apr 23, 2024
4368405
resolved comments
wangxiaoxuan273 May 6, 2024
06bbe80
resolved comment
wangxiaoxuan273 May 7, 2024
961075d
resolved comments
wangxiaoxuan273 May 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions example_pack_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ func ExamplePackManifest_imageV11() {
// 1. Set optional parameters
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
// 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",
},
}
Expand Down Expand Up @@ -70,8 +70,8 @@ func ExamplePackManifest_imageV10() {
// 1. Set optional parameters
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
// 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",
},
}
Expand Down
15 changes: 12 additions & 3 deletions pack.go
View file
Open in desktop
wangxiaoxuan273 marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down Expand Up @@ -93,7 +93,10 @@ 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. In order to
// 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.
Expand Down Expand Up @@ -126,6 +129,12 @@ 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, 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) {
switch packManifestVersion {
Expand Down
Loading