Minimal project descriptor

[jkutner]

Readable

See also #25

[jkutner]

Updated based on feedback from 12/5/19 WG meeting

[josegonzalez]

Is the idea here that platforms would convert into the project descriptor from whatever they support for metadata files?

Would unimplemented attributes raise an error? So a specific platform might extend the descriptor internally, for instance for extending os package support.

[jkutner]

Is the idea here that platforms would convert into the project descriptor from whatever they support for metadata files?

We haven't defined how a platform will support this file. We hope that eventually it will make it's way into the spec. If it does, we generally believe that lifecycle should in some way honor it (when possible). How that manifests itself is undecided (a new /lifecycle/describer or inline with each binary maybe?).

Would unimplemented attributes raise an error?

No. The only error condition we define is when exclude and include are both present.

So a specific platform might extend the descriptor internally, for instance for extending os package support.

Could this fit within the arbitrary [metadata] table?

[iainsproat]

Is the [project] property source-url intended to duplicate the property ("io.buildpacks.app.source".metadata.url) in RFC 0013?

Is it possible to include the metadata properties described in RFC 0013 within the project.toml file proposed in this RFC?

[steren]

While .toml is a great readable format, I have concerns that picking .toml might add more friction to users coming from the container world, which seems to have converged towards using .yaml. In my opinion, this is a data point that should be factored in when picking a format.

As a middle ground, maybe this proposal could say that .yaml and .json format are also accepted, but .toml is preferred (in the end, they all represent structured data, and .yaml is even a superset of .json).

[josegonzalez]

I think we should stick to toml. My reasoning is that all other parts of the buildpack spec use yaml, and as a platform maintainer, it would be quite frustrating to have to support other formats both in the platform itself and in support requests coming in from users.

The name project.toml also has fewer (no?) conflicts with other projects (I see that references to project.yaml in OpenStack and ArgoCD).

The json format doesn't allow for comments, which is why it wasn't picked.

[briandealwis]

include and exclude are used by the build process. How are the other fields here intended to be used? (Are they turned into image annotations?) Should there be builder and run-image fields?

[jkutner]

we're not specifying any behavior associated with the other fields.

I think any option on pack (including those you mentioned) is a good candidate for this descriptor. We batted around many different schemas, but are now trying to land on a very minimal subset of what was originally proposed.

[jkutner]

@iainsproat i'm not sure if RFC0013 was ever implemented, but we should probably align this with it. However, I think the app should be replaced with project ("app" has become too overloaded)

[hone]

@nebhale for the non SPDX use case, do people usually point to a URI or just include a file to the LICENSE on disk locally?

[nebhale]

The use of the URI is typically handled orthogonally from whether there's an SPDX value or not. The customers that have asked us for this don't so much want a link to the boiler-plate of the license (the SPDX takes care of that in most systems), but rather proof that the project uses that license. So you'll see:

[[metadata.dependencies.licenses]]
type = "GPL-2.0 WITH Classpath-exception-2.0"
uri  = "https://openjdk.java.net/legal/gplv2+ce.html"

[hone]

Overall, I like this. It seems flexible for future expansion and maps more directly to lifecycle. I left some comments with things I'm not going to block on, but am interested in opinions on.

[nebhale]

I've put some stuff in and would like to see some loosening of the requirements, but not enough to hold approval.

[nebhale]

The use of the URI is typically handled orthogonally from whether there's an SPDX value or not. The customers that have asked us for this don't so much want a link to the boiler-plate of the license (the SPDX takes care of that in most systems), but rather proof that the project uses that license. So you'll see:

[[metadata.dependencies.licenses]]
type = "GPL-2.0 WITH Classpath-exception-2.0"
uri  = "https://openjdk.java.net/legal/gplv2+ce.html"

[jkutner]

@nebhale i've addressed your feedback, and loosened the requirements on license type and uri.

[jromero]

Would launch.env be viable to be added as well? Thinking about environment variables that you want when your application launches that are outside of buildpacks (or override those provided by the buildpacks). Can be added later if we still need to discuss it further.

[jkutner]

I think launch.env is a bit more contentious, and we should discuss it in a separate update RFC.

[jkutner]

@hone @nebhale @sclevine Please review the very small change in f047502 and approve/reject. Otherwise the FCP will close on 1/16.

[jkutner]

I see now that this was merged in be3761d