From 57fbd745942cd494a74078a49857cb943ee1e397 Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Mon, 29 Mar 2021 20:04:57 +0100 Subject: [PATCH 1/3] Propose the creation of a best practices and guidelines repository Signed-off-by: Sambhav Kothari --- text/0000-best-practices-and-guidelines.md | 100 +++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 text/0000-best-practices-and-guidelines.md diff --git a/text/0000-best-practices-and-guidelines.md b/text/0000-best-practices-and-guidelines.md new file mode 100644 index 000000000..93b231c8a --- /dev/null +++ b/text/0000-best-practices-and-guidelines.md @@ -0,0 +1,100 @@ +# Meta +[meta]: #meta +- Name: Best practices and guidelines for Cloud Native Buildpacks +- Start Date: 2021-03-29 +- Author(s): [@samj1912](https://github.com/samj1912) +- RFC Pull Request: (leave blank) +- CNB Pull Request: (leave blank) +- CNB Issue: (leave blank) +- Supersedes: (put "N/A" unless this replaces an existing RFC, then link to that RFC) + +# Summary +[summary]: #summary + +As the CNB (Cloud Native Buildpacks) community grows and more people and organizations adopt it, there is a need for a set of guidelines that augment the CNB `spec` with a set of recommendations on how to design and implement - + +* Buildpacks +* Platforms + +These guidelines should not in any way be considered a mandate that `buildpack` and `platform` authors and users must follow, though they may find that those that conform well to these guidelines integrate better with the existing CNB ecosystem than those that do not. + + +# Motivation +[motivation]: #motivation + +> **NOTE** : The examples below are theoretical guidelines that are meant to serve as examples and are not meant to be the actual guidelines. + +Some of the motivations for the creating a set of guidelines are - + +## Better consistency and user experience for users and authors + +Examples - + +- A consistent naming scheme for `buildpacks`, `stack` IDs +- A consistent way to "configure" `buildpacks` like specifying environment variables through a project descriptor. + +## Transfer of knowledge and best pratices accrued over time by experienced users to newer users + +Examples - + +- Best practices around layer cache invalidation +- Best practices for a `platform` operator + + +## Better portability and reusability amongst different CNB ecosystems + +Examples - + +- Using `platform` agnostic constructs when writing and distributing `buildpacks` + + +## Allowing users to write maintainable and efficient `buildpacks` and `platforms` + +Examples - + +- Creation of buildpacks that attempt to do one thing and only one thing well and composing them using `meta-buildpacks` (Paketo ideology) + +## Avoiding common pitfalls that new users may be unaware of + +Examples - + +- `Bill-of-materials` needs to be regenerated on each run + + +# What it is +[what-it-is]: #what-it-is + +The `guidelines` would be contained in a new repository called `guidelines` which will be created in the `buildpacks` Github organization. This repository will be maintained by the `Learning team`. The repository should have seperate sections that target different personas and list guidelines and best practices specific to them - + +- Buildpack users +- Buildpack authors +- Platform operators +- Platform implementors + +These could be detailed sections or checklists that they can follow to ensure that they are following the best practices set by the guidelines. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? +N/A? + +# Alternatives +[alternatives]: #alternatives + +Have an extension to the spec that contains a list of `SHOULD`s and `MAY`s that capture the guidelines. + +# Prior Art +[prior-art]: #prior-art + +- [Best coding practices](https://en.wikipedia.org/wiki/Best_coding_practices) +- [Rust API guidelines](https://rust-lang.github.io/api-guidelines/about.html) +- [PEP8 - Python Style-guide](https://www.python.org/dev/peps/pep-0008/) + +# Unresolved Questions +[unresolved-questions]: #unresolved-questions + +- The exact set of guidelines that should be in the first cut of the repository +- Topics and details to cover +- Process for amending and creation of new guidelines +- How to ensure that the `spec` and the `guidelines` so they don't go out of sync with each other \ No newline at end of file From dab181326bc3d432bebc95b70579cd52e84a738c Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Wed, 31 Mar 2021 14:59:54 +0100 Subject: [PATCH 2/3] Add details about alternatives Signed-off-by: Sambhav Kothari --- text/0000-best-practices-and-guidelines.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/text/0000-best-practices-and-guidelines.md b/text/0000-best-practices-and-guidelines.md index 93b231c8a..1bb97b67f 100644 --- a/text/0000-best-practices-and-guidelines.md +++ b/text/0000-best-practices-and-guidelines.md @@ -32,6 +32,7 @@ Examples - - A consistent naming scheme for `buildpacks`, `stack` IDs - A consistent way to "configure" `buildpacks` like specifying environment variables through a project descriptor. +- A consistent format for `Bill-of-materials` metadata section to allow consistent rendering and parsing and easy integration with third-party dependency scanning tools. ## Transfer of knowledge and best pratices accrued over time by experienced users to newer users @@ -64,7 +65,7 @@ Examples - # What it is [what-it-is]: #what-it-is -The `guidelines` would be contained in a new repository called `guidelines` which will be created in the `buildpacks` Github organization. This repository will be maintained by the `Learning team`. The repository should have seperate sections that target different personas and list guidelines and best practices specific to them - +The `guidelines` would be contained in a sub-folder of the `buildpacks/docs` repository and it will be maintained by the `Learning team`. The folder should have separate sections that target different personas and list guidelines and best practices specific to them - - Buildpack users - Buildpack authors @@ -82,7 +83,14 @@ N/A? # Alternatives [alternatives]: #alternatives -Have an extension to the spec that contains a list of `SHOULD`s and `MAY`s that capture the guidelines. +## Create a new repository + +The guidelines and best-practices could be a separate repository under the buildpacks organization. This would allow the guidelines and best-practices to have a different review and approval process for the `guidelines`. + +## Extend the spec + +Have an extension to the spec that contains a list of `SHOULD`s and `MAY`s that capture the guidelines. This may however confuse users and may tie up something like the `spec` which is not geared towards end-users to `guidelines` which are supposed to be. + # Prior Art [prior-art]: #prior-art From c8e37a9ad84f68f17a30eaa640ae9581ef3180e4 Mon Sep 17 00:00:00 2001 From: Sambhav Kothari Date: Wed, 31 Mar 2021 15:33:05 +0100 Subject: [PATCH 3/3] Add drawbacks Signed-off-by: Sambhav Kothari --- text/0000-best-practices-and-guidelines.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/text/0000-best-practices-and-guidelines.md b/text/0000-best-practices-and-guidelines.md index 1bb97b67f..3831df9ec 100644 --- a/text/0000-best-practices-and-guidelines.md +++ b/text/0000-best-practices-and-guidelines.md @@ -77,8 +77,9 @@ These could be detailed sections or checklists that they can follow to ensure th # Drawbacks [drawbacks]: #drawbacks -Why should we *not* do this? -N/A? +## Why should we *not* do this? + +More maintenance and support burden on the Learning team. # Alternatives [alternatives]: #alternatives