Standardise the names and descriptions of languages buildpacks in the builder #408

edmorley · 2023-10-20T10:01:26Z

Currently there's a bit of inconsistency in the "Name" shown for each buildpack in the builder:

$ pack builder inspect heroku/builder:22
...
Buildpacks:
 ID                               NAME                              VERSION       HOMEPAGE
 heroku/go                        Heroku Go                         0.1.10        https://github.com/heroku/buildpacks-go
 heroku/gradle                    Gradle                            3.2.1         https://github.com/heroku/buildpacks-jvm
 heroku/java                      Java                              3.2.1         https://github.com/heroku/buildpacks-jvm
 heroku/jvm                       Heroku OpenJDK Buildpack          3.2.1         https://github.com/heroku/buildpacks-jvm
 heroku/maven                     Maven                             3.2.1         https://github.com/heroku/buildpacks-jvm
 heroku/nodejs                    Node.js                           1.1.7         https://github.com/heroku/buildpacks-nodejs
 heroku/nodejs-corepack           Heroku Node.js Corepack           1.1.7         https://github.com/heroku/buildpacks-nodejs
 heroku/nodejs-engine             Heroku Node.js Engine             1.1.7         https://github.com/heroku/buildpacks-nodejs
 heroku/nodejs-npm                NPM Buildpack                     1.1.7         https://github.com/heroku/buildpacks-nodejs
 heroku/nodejs-pnpm-install       Heroku Node.js pnpm install       1.1.7         https://github.com/heroku/buildpacks-nodejs
 heroku/nodejs-yarn               Heroku Node.js Yarn               1.1.7         https://github.com/heroku/buildpacks-nodejs
 heroku/php                       PHP                               0.1.1         https://github.com/heroku/buildpacks-php
 heroku/procfile                  Procfile                          2.0.1         https://github.com/heroku/procfile-cnb
 heroku/python                    Python                            0.7.1         https://github.com/heroku/buildpacks-python
 heroku/ruby                      Ruby                              2.1.0         https://github.com/heroku/buildpacks-ruby
 heroku/sbt                       sbt                               3.2.1         https://github.com/heroku/buildpacks-jvm
 heroku/scala                     Scala                             3.2.1         https://github.com/heroku/buildpacks-jvm

Specifically:

some prefix the name with "Heroku", others don't
some include the word "buildpack", others don't

In addition, we should perhaps try and distinguish between the composite buildpacks (formerly meta buildpacks) and the component buildpacks in the name.

These names come from the name field in buildpack.toml, e.g.:
https://github.com/heroku/procfile-cnb/blob/0574174d9634f0a4fed940efbb584b050dec30fc/buildpack.toml#L6

Whilst improving these, we should also audit the description fields, e.g.:
https://github.com/heroku/procfile-cnb/blob/0574174d9634f0a4fed940efbb584b050dec30fc/buildpack.toml#L8

...since the descriptions vary quite a bit too, and they are shown on e.g. the buildpack registry:
https://registry.buildpacks.io/buildpacks/heroku/procfile

The current descriptions are:

$ rg 'description = ' buildpacks*/**/buildpack.toml
buildpacks-ruby/buildpacks/ruby/buildpack.toml
8:description = "Official Heroku buildpack for using Ruby to target Cloud Native Buildpack (CNB) builds."

buildpacks-python/buildpack.toml
8:description = "Heroku's official Python Cloud Native Buildpack."

buildpacks-php/buildpacks/php/buildpack.toml
8:description = "Heroku's official PHP Cloud Native Buildpack."

buildpacks-jvm/meta-buildpacks/scala/buildpack.toml
8:description = "Official Heroku buildpack for Scala applications."

buildpacks-jvm/meta-buildpacks/java/buildpack.toml
8:description = "Official Heroku buildpack for Java applications."

buildpacks-jvm/buildpacks/sbt/buildpack.toml
9:description = "Official Heroku buildpack for sbt applications."

buildpacks-jvm/buildpacks/maven/buildpack.toml
9:description = "Official Heroku buildpack for Maven applications."

buildpacks-jvm/buildpacks/gradle/buildpack.toml
9:description = "Official Heroku buildpack for Gradle applications."

buildpacks-jvm/buildpacks/jvm/buildpack.toml
8:description = "Official Heroku buildpack for installing OpenJDK"

The following CNBs are missing a description:

$ rg --files-without-match '^description\s*=\s*' buildpacks*/**/buildpack.toml | sort
buildpacks-go/buildpack.toml
buildpacks-jvm/buildpacks/jvm-function-invoker/buildpack.toml
buildpacks-jvm/meta-buildpacks/java-function/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-corepack/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-engine/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-function-invoker/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-npm-engine/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-npm-install/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-pnpm-install/buildpack.toml
buildpacks-nodejs/buildpacks/nodejs-yarn/buildpack.toml
buildpacks-nodejs/buildpacks/npm/buildpack.toml
buildpacks-nodejs/meta-buildpacks/nodejs-function/buildpack.toml
buildpacks-nodejs/meta-buildpacks/nodejs/buildpack.toml

GUS-W-14121598.

The text was updated successfully, but these errors were encountered:

edmorley · 2023-10-20T10:12:05Z

For name, I think we should:

Always prefix the name with "Heroku" (given that in the CNB world buildpacks can be from a variety of vendors)
Not use the word "buildpack" since it's redundant
Try to distinguish between composite and component buildpacks by having the component buildpacks use a semicolin prefix. ie: Heroku <Lang> for the composite and Heroku <Lang>: <Some component> for the component.

edmorley · 2023-10-20T16:04:04Z

For description, the only place this is used as far as I can see is the CNB registry - however, that's still an important use-case. I think we should:

Add descriptions to any buildpack that is currently missing them
Remove the phrase "Official" since it's redundant given these buildpacks are under the heroku namespace, plus it sounds a bit over the top IMO
Consistently use the term "buildpack" rather than "cloud native buildpack" (since all of the buildpacks on the CNB registry are CNBs)
Label component buildpacks in such a way that people don't accidentally use them without meaning to

edmorley · 2023-10-23T11:43:27Z

For keywords, I think we should:

Always include "heroku"
Not spam dozens of language specific keywords, but pick the most common
Make sure the composite buildpacks include any notable keywords for component buildpacks they contain. eg: The Java composite buildpack should probably include the "maven" keyword too, given one of its component buildpacks is for Maven support
Remove generic keywords from the component buildpacks, since we only want people to find those that are needing the specific component (eg "npm") and not people looking for the overall application solution (eg "node.js")

Malax · 2023-10-23T11:59:10Z

Try to distinguish between composite and component buildpacks by having the component buildpacks use a semicolin prefix. ie: Heroku <Lang> for the composite and Heroku <Lang>: <Some component> for the component.

This will be hard to do correctly for some of the more polyglot ecosystems such as JVM, CLR and Node. Gradle for example is used with various languages and we therefore can't associate it with a single Heroku <Lang> prefix.

We could loosen this up a bit and make it a Heroku <Ecosystem> prefix which in some cases such as Python will be the same as the language, basically what we're already doing with the monorepo names: buildpacks-jvm vs buildpacks-python.

Apart from this small bit, I'm 👍🏻 on the proposals so far. :)

edmorley · 2023-10-23T15:13:46Z

Yeah agree about the prefix being harder to do in some ecosystems.

Label component buildpacks in such a way that people don't accidentally use them without meaning to

After speaking with Manuel, we settled on descriptions like this for composite buildpacks:

Heroku's buildpack for Java applications.

vs this for component buildpacks (that aren't standalone in their own right):

Heroku's Maven buildpack. A component of the 'heroku/java' buildpack.

edmorley · 2023-10-23T17:54:59Z

Opened:

Adjusts the buildpack `name`, `description` and `keywords` in the `buildpack.toml` of all buildpacks to match the style discussed in: heroku/cnb-builder-images#408 These fields are used by the CNB registry and can also be seen in the output of `pack builder inspect`. They are not used by `pack build` or Kodon. In addition to standardising the metadata, one of the objectives here is to ensure users don't accidentally use component buildpacks when they really wanted the composite buildpack. The `keywords` field has intentionally been omitted from the functions buildpacks since they are EOL and so don't want to be made more discoverable. (The CNB registry doesn't currently ingest/display the keywords currently, but may in the future.) Lastly, I've cleaned up the `[metadata]` table/subtables to match the concise style used by the Procfile and Python CNBs. GUS-W-14121598.

Adjusts the buildpack `name`, `description` and `keywords` in `buildpack.toml` to match the style discussed in: heroku/cnb-builder-images#408 These fields are used by the CNB registry and can also be seen in the output of `pack builder inspect`. They are not used by `pack build` or Kodon. In addition, I've cleaned up the `[metadata]` table/subtables to match the more concise style used by the Procfile and Python CNBs. GUS-W-14121598.

Adjusts the buildpack `name`, `description` and `keywords` in the `buildpack.toml` of all buildpacks to match the style discussed in: heroku/cnb-builder-images#408 The `keywords` field has intentionally been omitted from the functions buildpacks since they are EOL and so don't want to be made more discoverable. (The CNB registry doesn't currently ingest/display the keywords currently, but may in the future.) Lastly, I've cleaned up the `[metadata]` table/subtables to match the concise style used by the Procfile and Python CNBs. GUS-W-14121598.

Adjusts the buildpack `name` and `description` in `buildpack.toml` to match the style discussed in: heroku/cnb-builder-images#408 These fields are used by the CNB registry and can also be seen in the output of `pack builder inspect`. They are not used by `pack build` or Kodon. In addition, I've cleaned up the `[metadata]` table/subtables to match the more concise style used by the Procfile and Python CNBs. GUS-W-14121598.

Adjusts the buildpack `name` and `description` in `buildpack.toml` to match the style discussed in: heroku/cnb-builder-images#408 These fields are used by the CNB registry and can also be seen in the output of `pack builder inspect`. They are not used by `pack build` or Kodon. GUS-W-14121598.

Adds the buildpack `description` to `buildpack.toml` with a style matching that discussed in: heroku/cnb-builder-images#408 The `description` field is displayed on the CNB registry's page for the buildpack. In addition, I've cleaned up the `[metadata]` table/subtables to match the more concise style used by the Procfile and Python CNBs. GUS-W-14121598.

Adjusts the buildpack `name`, `description` and `keywords` in `buildpack.toml` to match the style discussed in: heroku/cnb-builder-images#408 These fields are used by the CNB registry and can also be seen in the output of `pack builder inspect`. They are not used by `pack build` or Kodon. GUS-W-14121598.

So that: - The naming style matches that chosen in #408 - It's clearer that these are shimmed buildpacks and not the native CNB versions of the buildpacks with the same name GUS-W-14121598.

edmorley · 2023-10-25T16:34:10Z

This is now complete.

The updated descriptions can be seen in the upstream CNB registry listings:
https://registry.buildpacks.io/searches/heroku

eg:
https://registry.buildpacks.io/buildpacks/heroku/nodejs
https://registry.buildpacks.io/buildpacks/heroku/nodejs-yarn

The standardised names can be seen in the output of pack builder inspect.

eg:

$ pack builder inspect heroku/builder:22
...
Buildpacks:
  ID                                NAME                               VERSION        HOMEPAGE
  heroku/go                         Heroku Go                          0.1.11         https://github.com/heroku/buildpacks-go
  heroku/gradle                     Heroku Gradle                      4.0.0          https://github.com/heroku/buildpacks-jvm
  heroku/java                       Heroku Java                        4.0.0          https://github.com/heroku/buildpacks-jvm
  heroku/jvm                        Heroku OpenJDK                     4.0.0          https://github.com/heroku/buildpacks-jvm
  heroku/maven                      Heroku Maven                       4.0.0          https://github.com/heroku/buildpacks-jvm
  heroku/nodejs                     Heroku Node.js                     2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/nodejs-corepack            Heroku Node.js Corepack            2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/nodejs-engine              Heroku Node.js Engine              2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/nodejs-npm-engine          Heroku Node.js npm Engine          2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/nodejs-npm-install         Heroku Node.js npm Install         2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/nodejs-pnpm-install        Heroku Node.js pnpm install        2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/nodejs-yarn                Heroku Node.js Yarn                2.0.0          https://github.com/heroku/buildpacks-nodejs
  heroku/php                        Heroku PHP                         0.1.2          https://github.com/heroku/buildpacks-php
  heroku/procfile                   Heroku Procfile                    2.0.2          https://github.com/heroku/procfile-cnb
  heroku/python                     Heroku Python                      0.7.2          https://github.com/heroku/buildpacks-python
  heroku/ruby                       Heroku Ruby                        2.1.1          https://github.com/heroku/buildpacks-ruby
  heroku/sbt                        Heroku sbt                         4.0.0          https://github.com/heroku/buildpacks-jvm
  heroku/scala                      Heroku Scala                       4.0.0          https://github.com/heroku/buildpacks-jvm

And for the images contained shimmed classic buildpacks:

$ pack builder inspect heroku/builder-classic:22
...
Buildpacks:
  ID                     NAME                            VERSION        HOMEPAGE
  heroku/clojure         Heroku Clojure (Shimmed)        0.0.0          -
  heroku/go              Heroku Go (Shimmed)             0.0.0          -
  heroku/gradle          Heroku Gradle (Shimmed)         0.0.0          -
  heroku/java            Heroku Java (Shimmed)           0.0.0          -
  heroku/nodejs          Heroku Node.js (Shimmed)        0.0.0          -
  heroku/php             Heroku PHP (Shimmed)            0.0.0          -
  heroku/procfile        Heroku Procfile                 2.0.2          https://github.com/heroku/procfile-cnb
  heroku/python          Heroku Python (Shimmed)         0.0.0          -
  heroku/ruby            Heroku Ruby (Shimmed)           0.0.0          -
  heroku/scala           Heroku Scala (Shimmed)          0.0.0          -

To make the name consistent with our other CNBs, eg: https://github.com/heroku/buildpacks-python/blob/ee25c70c647a2d5d11b19bfc2a4bc1ab5598138c/buildpack.toml#L6 https://github.com/heroku/buildpacks-nodejs/blob/df5f1de2e6fde1ef98701740f80bf83b2975bedd/meta-buildpacks/nodejs/buildpack.toml#L6 And also to add some additional keywords. See also: heroku/cnb-builder-images#408

edmorley self-assigned this Oct 23, 2023

edmorley mentioned this issue Oct 24, 2023

Update display name of shimmed buildpacks #410

Merged

edmorley closed this as completed Oct 25, 2023

edmorley mentioned this issue Feb 15, 2024

Apt - Minimum Viable Buildpack - 01 - Project Structure heroku/buildpacks-deb-packages#1

Merged

edmorley mentioned this issue Mar 7, 2024

Update README.md according to Heroku CNB guidelines heroku/buildpacks-procfile#217

Merged

edmorley mentioned this issue Oct 15, 2024

Update buildpack name/keywords heroku/buildpacks-deb-packages#59

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Standardise the names and descriptions of languages buildpacks in the builder #408

Standardise the names and descriptions of languages buildpacks in the builder #408

edmorley commented Oct 20, 2023 •

edited

Loading

edmorley commented Oct 20, 2023 •

edited

Loading

edmorley commented Oct 20, 2023

edmorley commented Oct 23, 2023 •

edited

Loading

Malax commented Oct 23, 2023

edmorley commented Oct 23, 2023

edmorley commented Oct 23, 2023 •

edited

Loading

edmorley commented Oct 25, 2023

Standardise the names and descriptions of languages buildpacks in the builder #408

Standardise the names and descriptions of languages buildpacks in the builder #408

Comments

edmorley commented Oct 20, 2023 • edited Loading

edmorley commented Oct 20, 2023 • edited Loading

edmorley commented Oct 20, 2023

edmorley commented Oct 23, 2023 • edited Loading

Malax commented Oct 23, 2023

edmorley commented Oct 23, 2023

edmorley commented Oct 23, 2023 • edited Loading

edmorley commented Oct 25, 2023

edmorley commented Oct 20, 2023 •

edited

Loading

edmorley commented Oct 20, 2023 •

edited

Loading

edmorley commented Oct 23, 2023 •

edited

Loading

edmorley commented Oct 23, 2023 •

edited

Loading