Add conventions for app source metadata

Signed-off-by: Javier Romero <[email protected]>

Author: jromero

content/docs/app-developer-guide/_index.md

@@ -1,5 +1,5 @@
 +++
-title="App Developer's Guide"
+title="App Developer Guide"
 weight=4
 include_summaries=true
 expand=true

content/docs/buildpack-author-guide/_index.md

@@ -1,5 +1,5 @@
 +++
-title="Buildpack Author's Guide"
+title="Buildpack Author Guide"
 weight=4
 include_summaries=true
 expand=true

content/docs/operator-guide/_index.md

@@ -1,5 +1,5 @@
 +++
-title="Operator's Guide"
+title="Operator Guide"
 weight=5
 include_summaries=true
 expand=true

content/docs/platform-guide/_index.md

@@ -0,0 +1,6 @@
++++
+title="Platform Guide"
+weight=6
+include_summaries=true
+expand=true
++++

content/docs/platform-guide/conventions/_index.md

@@ -0,0 +1,6 @@
++++
+title="Conventions"
+weight=1
+include_summaries=true
+expand=false
++++

content/docs/platform-guide/conventions/source-metadata.md

@@ -0,0 +1,146 @@
++++
+title="Source Metadata"
+weight=1
+summary="Conventions for declaring app source information in the app image."
+tags=["spec:platform/0.6", "spec:project-descriptor/0.2"]
++++
+
+## Summary
+
+The following are conventions for declaring different type of source inputs. This information is provided to the [lifecycle][lifecycle] using [project-metadata.toml][project-metadata].
+
+## Sources
+
+### Types
+
+The following types are concrete source types and can use any keys as long as they don't overlap with [additive](#additive) sources.
+
+#### Git
+
+- #### `type` _(string,required)_
+  Must be `git`
+
+- #### `source` _(required)_
+
+  - `version` _(required)_
+    
+    - `commit` _(string,required)_\
+      Full commit hash
+
+    - `describe` _(string,optional)_\
+      Description of commit (see `git describe`)
+
+  - `metadata`  _(optional)_
+    
+    - `repository` _(string,optional)_\
+      Repository URL
+
+    - `refs` _(string,optional)_\
+      Additional relevant Git references
+
+###### Example
+
+```toml
+[source]
+type = "git"
+
+  [source.version]
+  commit = "63a73f1b0f2a4f6978c19184b0ea33ad3f092913"
+  describe = "v0.18.1-2-g3f092913"
+
+  [source.metadata]
+  repository = "https://github.com/myorg/myrepo.git"
+  refs = ["master", "v3.0"]
+```
+
+#### Image
+
+- #### `type` _(string,required)_
+  Must be `image`
+
+- #### `source` _(required)_
+
+  - `version` _(required)_
+    
+    - `digest` _(string,required)_\
+      Image digest
+
+  - `metadata`  _(optional)_
+    
+    - `path` _(string,optional)_\
+      Absolute path to source in image
+
+    - `repository` _(string,optional)_\
+      Fully-qualified image name
+
+    - `refs` _(string,optional)_\
+      Additional relevant image names/tags
+
+###### Example
+
+```toml
+[source]
+type = "image"
+
+  [source.version]
+  digest = "146c4bce42545e6a4575283b32a7f01924ef86ce848273079693a42b52b27321"
+
+  [source.metadata]
+   path = "/source"
+   repository =  "index.docker.io/example/image:latest"
+   refs = ["index.docker.io/example/image:mytag", "index.docker.io/example/image@sha256:146c4bce42545e6a4575283b32a7f01924ef86ce848273079693a42b52b27321"]
+```
+
+### Additive
+
+The following source information is considered additive and should not overlap with source [types](#types).
+
+#### `project.toml`
+
+- #### `type` _(string,required)_
+  Must be `project` **(only if no other type is present)**
+
+- #### `source` _(required)_
+
+  - `version` _(required)_
+    
+    - `version` _(string,optional)_\
+      Version as declared in `_.version`
+
+  - `metadata`  _(optional)_
+    
+    - `url` _(string,optional)_\
+      URL as declared in `_.source-url`
+
+###### Example (standalone)
+
+```toml
+[source]
+type = "project"
+
+  [source.version]
+  version = "1.2.3"
+
+  [source.metadata]
+  url = "https://github.com/example/repo"
+```
+
+###### Example (w/ Image)
+
+```toml
+[source]
+type = "image"
+
+  [source.version]
+  digest = "146c4bce42545e6a4575283b32a7f01924ef86ce848273079693a42b52b27321"
+  version = "1.2.3"
+
+  [source.metadata]
+  path = "/source"
+  repository =  "index.docker.io/example/image:latest"
+  refs = ["index.docker.io/example/image:mytag", "index.docker.io/example/image@sha256:146c4bce42545e6a4575283b32a7f01924ef86ce848273079693a42b52b27321"]
+  url = "https://github.com/example/repo"
+```
+
+[lifecycle]: /docs/concepts/components/lifecycle/
+[project-metadata]: https://github.com/buildpacks/spec/blob/platform/0.7/platform.md#project-metadatatoml-toml

tools/go.mod

@@ -4,26 +4,23 @@ go 1.14
 
 require (
 	github.com/Azure/azure-sdk-for-go v42.3.0+incompatible // indirect
-	github.com/buildpacks/pack v0.19.0
+	github.com/buildpacks/pack v0.20.0
 	github.com/containerd/containerd v1.5.0-beta.4 // indirect
 	github.com/containerd/stargz-snapshotter/estargz v0.5.0 // indirect
 	github.com/docker/cli v20.10.5+incompatible // indirect
-	github.com/docker/docker v20.10.5+incompatible // indirect
 	github.com/gohugoio/hugo v0.82.0
 	github.com/hashicorp/golang-lru v0.5.3 // indirect
 	github.com/jromero/ugo v0.0.0-20200909162226-1fa70f1e3823 // indirect
 	github.com/kevinburke/ssh_config v0.0.0-20201106050909-4977a11b4351 // indirect
 	github.com/moby/term v0.0.0-20201216013528-df9cb8a40635 // indirect
 	github.com/sabhiram/go-gitignore v0.0.0-20201211210132-54b8a0bf510f // indirect
 	github.com/sirupsen/logrus v1.8.1 // indirect
-	github.com/spf13/cobra v1.1.3
+	github.com/spf13/cobra v1.2.1
 	github.com/vdemeester/k8s-pkg-credentialprovider v1.18.1-0.20201019120933-f1d16962a4db // indirect
 	golang.org/x/crypto v0.0.0-20210322153248-0c34fe9e7dc2 // indirect
 	golang.org/x/sync v0.0.0-20210220032951-036812b2e83c // indirect
 	golang.org/x/term v0.0.0-20210317153231-de623e64d2a6 // indirect
 	gonum.org/v1/netlib v0.0.0-20190331212654-76723241ea4e // indirect
-	google.golang.org/genproto v0.0.0-20210325224202-eed09b1b5210 // indirect
-	google.golang.org/grpc v1.36.1 // indirect
 	k8s.io/code-generator v0.20.1 // indirect
 	sigs.k8s.io/structured-merge-diff v0.0.0-20190525122527-15d366b2352e // indirect
 )