Document use of Cloud Native Buildpacks

[loewenstein-sap]

Since RFC0028 has been accepted, most of the work to support Cloud Native Buildpacks has been implemented and merged.

With RFC0031 even the support for Cloud Native Buildpacks as system buildpacks has been accepted and the implementation is currently in review.

This issue is meant to track documentation efforts around the use of Cloud Native Buildpacks in Cloud Foundry and I would like to get this started with a proposal for the documentation structure.

Looking at the current structure of https://docs.cloudfoundry.org/buildpacks/, we have the following and need to make sure Cloud Native Buildpacks fit in this nicely and naturally:

• Buildpacks
  • Using buildpacks
    • Working with buildpacks in Cloud Foundry
    • Stack association
    • Pushing an app with multiple buildpacks
    • Using a proxy server
    • Supported binary dependencies
    • Configuring a production service
  • Binary buildpack
  • Go buildpack
  • ...
  • Customizing and developing buildpacks in Cloud Foundry

While there are similarities - in the end all versions of buildpacks are concerned with assembling an execution filesystem for different programming languages and environments - it seems to make sense to have separate documentation trees. We might want to make sure that similar topics are presented in a similar and recognizable way, but merging distinct information deeply will likely just create a bad experience for users of classical Cloud Foundry Buildpacks as well as Cloud Native Buildpacks.

We would propose to go for the following structure:

• Buildpacks
  • Cloud Foundry Buildpacks
    • Using buildpacks
      • Working with buildpacks in Cloud Foundry
      • Stack association
      • Pushing an app with multiple buildpacks
      • Using a proxy server
      • Supported binary dependencies
      • Configuring a production service
    • Binary buildpack
    • Go buildpack
    • ...
    • Customizing and developing buildpacks in Cloud Foundry
  • Cloud Native Buildpacks
    • What are Cloud Native Buildpacks?
      This would mainly focus on the historical background of buildpacks from v1 in Heroku to v2 in both Heroku and Cloud Foundry and finally v3 as a specification project in the CNCF and Paketo as a reference implementation from the Cloud Foundry Community.
    • Using buildpacks
      This would pick up the topics from the corresponding chapter and subchapters of the CF buildpacks part above where and when it makes sense.
    • Paketo buildpacks
      Instead of listing individual buildpacks, it seems to make more sense to reference the Paketo documentation more broadly.
      Note: Actually, this might stay blank for now, as there is currently no system buildpack support yet and once this is there, a separate RFC is needed that might decide to take Paketo buildpacks as (batteries included) system buildpacks for cf-deployment. Only then it makes sense to give Paketo this level of attention.
    • Developing your own buildpacks
      This would mainly reference buildpacks.io (and might reference paketo.io) and should not duplicate documentation that is separately available.

Additionally, we of course need to make sure that e.g. cf cli changes and manifest.yaml changes are documented in the proper places.

What you think?

[pspinrad]

Makes sense, thanks! A couple of q's:

• For the high-level v2 vs v3 buildpacks explanation, WDYT of putting most of that explanation in the top level Buildpacks page, and point to it from a shorter "What are Cloud Native Buildpacks?" section in the top level Cloud Native Buildpacks page, rather than putting a whole page about v2 vs v3 under CNB's? Seems like it's good context for what's under both the CF and CNB sections.
• For Using Buildpacks, how similar are the instructions for v2 vs v3? If they're mostly similar, might make sense to make this a single page under top-level Buildpacks and call out the v2 vs v3 differences inline wherever needed. But if they diverge a bunch, better as separate. Judgement call.

Also-- what's Paketo? Is that a specific standard for Cloud Native / v3 buildpacks, or a catalog of them, or?

Thanks again--

[c0d1ngm0nk3y]

I started with that and have some questions:

Regarding the tree...

• I wonder what the naming should be. After all, it is more a v2 vs. v3 thing, right?
• My impression is that the granularity is a bit strange. For v2, the buildpacks are described in detail and even per buildpack and v3, it is more an overview with referring to paketo (listing the buildpacks makes probably not much sense)

Regarding the index site....

• Having both in there is a bit to much for this page imho, wdyt? So we could...
  • Reduce the linked content, but that would reduce the available information for v2
  • Only mention v2 which would feel odd to not mention the newer v3 buildpacks

[loewenstein-sap]

@pspinrad have you had a chance to have a look?

[pspinrad]

Hi -- yes, I'd like to discuss, figure out how to do what we want with consistent naming and without changing source file structure as mentioned here. I'd also like to include @anthonydahanne in the discussion. Sound good? What time zone are you in? (I'm in California). Thanks!

[loewenstein-sap]

We're all located in CET, maybe start a doodle or similar with some times (in your mornings) that would work for you - would that work?

[pspinrad]

Sounds good-- here's Doodle invite, and I'll also send to Ralf and Anthony.

[c0d1ngm0nk3y]

Sounds good-- here's Doodle invite, and I'll also send to Ralf and Anthony.

Thanks. Just pick any occurrence where some of our team (Jan, Pavel, Johannes, me) have time. That should be fine from our side.

[beyhan]

The docs has been release in https://docs.cloudfoundry.org/buildpacks/cnb/index.html. Can we close this?

[pspinrad]

Closing -- thanks, all!