Merge pull request #81 from buildpacks/project-metadata

Project metadata

platform.md

@@ -28,6 +28,7 @@ Examples of a platform might include:
 6. [Data Format](#data-format)
    1. [order.toml (TOML)](#order.toml-(toml))
    2. [group.toml (TOML)](#group.toml-(toml))
+   3. [project-metadata.toml (TOML)](#project-metadata.toml-(toml))
 
 
 ## Platform API Version
@@ -81,7 +82,8 @@ The platform MUST ensure that:
 - The image config's `Env` field has the environment variable `CNB_GROUP_ID` set to the primary GID of the user specified in the `User` field.
 - The image config's `Label` field has the label `io.buildpacks.stack.id` set to the stack ID.
 - The image config's `Label` field has the label `io.buildpacks.stack.mixins` set to a JSON array containing mixin names for each mixin applied to the image.
-
+
+#### Detection phase
 To initiate the detection phase, the platform MUST invoke the `/cnb/lifecycle/detector` executable with the user and environment defined in the build image config.
 Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values.
 
@@ -96,6 +98,7 @@ Where:
 - `-group` MUST specify output to a `group.toml` file path as defined in the [Data Format](#data-format) section.
 - `-plan` MUST specify output to a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md).
 
+#### Build phase
 To initiate the build phase, the platform MUST invoke the `/cnb/lifecycle/builder` executable with the user and environment defined in the build image config.
 Invoking this executable with no flags is equivalent to the following invocation including all accepted flags and their default values.
 
@@ -109,6 +112,12 @@ Where:
 - `-group` MUST specify input from a `group.toml` file path as defined in the [Data Format](#data-format) section.
 - `-plan` MUST specify input from a Build Plan as defined in the [Buildpack Interface Specification](buildpack.md).
 
+#### Export phase
+To initiate the export phase, the platform MUST invoke the `/cnb/lifecycle/exporter` executable with the user and environment defined in the build image config.
+
+The platform MAY provide a [`project-metadata.toml`](#project-metadata.toml-(toml)) file in the platform directory.
+The platform MAY provide a `-platform-project` flag or `CNB_PROJECT_METADATA_PATH` environment variable to specify the path to this file. If not provided, the default path is `./project-metadata.toml`.
+
 ### Run Image
 
 The platform MUST provide the lifecycle with a reference to the run image during the export phase.
@@ -142,6 +151,11 @@ The buildpacks directory MUST contain unarchived buildpacks such that:
 - Each top-level directory is a buildpack ID.
 - Each second-level directory is a buildpack version.
 
+## Exported Image
+The Exported image containing the compiled application is generated by the Build Image during the [Export Phase](#export-phase).
+
+If the `/cnb/lifecycle/exporter` is provided with a `project-metadata.toml` file, the lifecycle MUST add a `io.buildpacks.project.metdata` image config label to the Exported image. This label value MUST be the encoded JSON format of the `project-metadata.toml` contents, as described in the [data-format](#data-format) section.
+
 ## Security Considerations
 
 The platform SHOULD run each phase of the lifecycle in an isolated container to prevent untrusted app and buildpack code from accessing storage credentials needed during the export and analysis phases.
@@ -199,3 +213,22 @@ group = [
 Where:
 
 - Both `id` and `version` MUST be present for each buildpack object in a group.
+
+### project-metadata.toml (TOML)
+
+```toml
+[source]
+type = "<source type>"
+
+[source.version]
+# arbitrary data describing version
+
+[source.metadata]
+# arbitrary data
+
+```
+Where:
+- All values are optional
+- `type`, if present, SHOULD contain the type of location where the provided app source is stored (e.g `git`, `s3`)
+- `version`, if present, SHOULD contain data uniquely identifying the particular version of the provided source
+- `metadata` MAY contain additional arbitrary data about the provided source