Convention: app source metadata

[jromero]

If I recall correctly, when RFC#13 (app source metadata) was introduced, the concrete specification for how different type of sources would be represented was left out of the specification. I believe this was in order to allow for conventions to fill the need of countless possible types.

I'd like to propose the following conventions to be used on pack and for them to be codified as "conventions" in https://buildpacks.io/docs/.

App Source Conventions

Type git

Based on already completed work on kpack:

[source]
type = "git"

  [source.version]
  commit = "63a73f1b0f2a4f6978c19184b0ea33ad3f092913"
  describe = "v0.18.1-2-g3f092913"

  [source.metadata]
  refs = ["master", "v3.0"]
  repository = "https://github.com/myorg/myrepo.git"

Type image

When source is an image (kpack feature):

[source]
type = "image"

  [source.version]
  digest = "146c4bce42545e6a4575283b32a7f01924ef86ce848273079693a42b52b27321"

  [source.metadata]
   path = "/source"
   repository =  "index.docker.io/example/image"
   refs = ["example/image:mytag"]

Type project

When declared in project.toml as:

[project]
version = "1.0.2"
source-url = "https://github.com/buildpacks/pack"

The generated metadata would be:

[source]
type = "project"

  [source.version]
  declared = "1.0.2"

  [source.metadata]
  url = "https://github.com/buildpacks/pack"

Open Questions

• What's expected from the platform when the source has both .git information as well as project.toml?
  • Proposal: In the short term, .git takes precedence over project.toml due to its more precise nature.
  • Proposal: see Alternative

[jromero]

Alternative

As an alternative to having project.toml compete with other types. I wonder if project.toml could simply augment the other types.

project.toml

For example, given project.toml:

[project]
version = "1.0.2"
source-url = "https://github.com/buildpacks/pack"

... with Git information

and some .git/ or git.properties information, the following would be the aggregate:

[source]
type = "git"

  [source.version]
  # from project.toml
  version = "1.0.2"
  # from git
  commit = "63a73f1b0f2a4f6978c19184b0ea33ad3f092913"
  # from git
  describe = "v0.18.1-2-g3f092913"

  [source.metadata]
  # from project.toml
  url = "https://github.com/buildpacks/pack"
  # from git
  refs = ["master", "v3.0"]
  # from git
  repository = "https://github.com/myorg/myrepo.git"

... with Image information

and some image information, the following would be the aggregate:

[source]
type = "image"

  [source.version]
  # from project.toml
  version = "1.0.2"
  # from image
  digest = "146c4bce42545e6a4575283b32a7f01924ef86ce848273079693a42b52b27321"

  [source.metadata]
  # from project.toml
  url = "https://github.com/buildpacks/pack"
  # from image
   path = "/source"
  # from image
  repository =  "index.docker.io/example/image"
  # from image
  refs = ["example/image:mytag"]

[jromero]

Created this PR to docs: buildpacks/docs#390