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

Buildpack API Modes #100

Merged
merged 4 commits into from
Jul 7, 2020
Merged

Buildpack API Modes #100

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a10c6fa
Update buildpack spec for RFC-0041
ekcasey Jun 24, 2020
a468b18
Update buildpack.md
ekcasey Jun 25, 2020
2ca6cb7
Apply suggestions from code review
ekcasey Jul 7, 2020
60f48c4
Merge branch 'buildpack/0.3' into buildpack-api-modes
nebhale Jul 7, 2020
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
24 changes: 19 additions & 5 deletions buildpack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th

- [Buildpack Interface Specification](#buildpack-interface-specification)
- [Table of Contents](#table-of-contents)
- [Buildpack API Version](#buildpack-api-version)
- [Buildpack Interface](#buildpack-interface)
- [Buildpack API Compatibility](#buildpack-api-compatibility)
- [Key](#key)
- [Detection](#detection)
- [Build](#build)
Expand Down Expand Up @@ -69,11 +71,25 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
- [Buildpack Implementations](#buildpack-implementations)
- [Order Buildpacks](#order-buildpacks)

## Buildpack API Version
This document specifies Buildpack API version `0.3`

Buildpack API versions:
- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
- When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes

## Buildpack Interface

The following specifies the interface implemented by executables in each buildpack.
The lifecycle MUST invoke these executables as described in the Phase sections.

### Buildpack API Compatibility
Given a buildpack declaring `<buildpack API Version>` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle:
- MUST either conform to the matching version of this specification when interfacing with the buildpack or
- return an error to the platform if it does not support `<buildpack API Version>`

The lifecycle MAY return an error to the platform if two or more buildpacks within a group declare buildpack API versions that the lifecycle cannot support together within a single build, even if both are supported independently.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on the RFC:

the spec may not change in a way that precludes buildpacks implementing different 0.x APIs from running together.

This seems contradictory, but I assume atm you mean 0.1 and 0.2+?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it is contradictory. This error case would potentially apply to a future 0.4/1.0 incompatibility.


### Key

| Mark | Meaning
Expand Down Expand Up @@ -815,7 +831,7 @@ For a given layer, the buildpack MAY specify:
This section describes the 'Buildpack descriptor'.

```toml
api = "<buildpack API>"
api = "<buildpack API version>"

[buildpack]
id = "<buildpack ID>"
Expand Down Expand Up @@ -856,12 +872,10 @@ If an `order` is specified, then `stacks` MUST NOT be specified.

**The buildpack API:**

*Key: `api = "<buildpack API>"`*
*Key: `api = "<buildpack API version>"`*
- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
- MUST describe the implemented buildpack API.
- SHALL indicate compatibility with a given lifecycle according to the following rules:
- When `<major>` is `0`, the buildpack is only compatible with lifecycles implementing that exact buildpack API.
- When `<major>` is greater than `0`, the buildpack is only compatible with lifecycles implementing buildpack API `<major>.<minor>`, where `<major>` of the lifecycle equals `<major>` of the buildpack and `<minor>` of the lifecycle is greater than or equal to `<minor>` of the buildpack.
- SHOULD indicate the lowest compatible `<minor>` IF buildpack behavior is consistent with multiple `<minor>` versions of a given `<major>`

#### Buildpack Implementations

Expand Down