New page "Basics of BuildPacks" under the Getting Started side menu #688
Conversation
- Changed `app-journey` weight to 3 to move it down - Added a new "Basics of Buildpacks" page - Added a new image to depict what constitutes a `lifecycle` Signed-off-by: QuillPusher <[email protected]>
QuillPusher
force-pushed
the
add_buildpack_basics_under_getting_started
branch
from
b13b97f
to
e25054a
Compare
| A `buildpack` is software that transforms application source code into | ||
| executable files by analyzing the code and determining the best way to | ||
| build it. |
There was a problem hiding this comment.
I've always found it difficult to describe what an individual buildpack is! A buildpack is a small software component that does something. Would we be better off here to explain by example? i.e. provide an example of a "distribution" buildpack, an a "build process" buildpack?
There was a problem hiding this comment.
- How about adding the following paragraph under this definition:
Buildpacks have many shapes and forms. For example, a 'Distribution BuildPack' is a pre-built and tested buildpack that is ready for distribution to application developers. A Distribution Buildpack includes a set of buildpacks that are packaged together and can be used to build applications in different environments.
'Paketo Buildpacks' is a distribution buildpack for building applications in Java, Go, Python, Ruby, etc. The buildpacks included in 'Paketo Buildpacks' work together to create application container images that can run on any platform that supports container images (e.g., Cloud Foundry, Docker, Kubernetes, etc.).
Source: https://paketo.io/
- I couldn't find much information on "build process" buildpacks, can you please elaborate on this?
P.s., I'm still connecting the dots with the core concepts, please see if the description is conceptually correct.
content/docs/buildpack-basics.md
Outdated
| buildpack execution. Next, `launcher` can be used to launch the application. | ||
| Finally, `rebase` can be used to push the latest changes to an existing | ||
| buildpack. All of these steps are part of a lifecycle. |
There was a problem hiding this comment.
Lifecycle and launcher can be used independently of each other, should we mix them both in the same initial description?
There was a problem hiding this comment.
- How about the following (I guess the image may also need to be updated, please let me know the required changes):
A lifecycle is a series of steps that are used to create and manage a buildpack. The cumulative create step can be used to analyze, detect, restore, build, and export buildpack execution. All of these steps are part of a lifecycle. You can also re-enter a lifecycle using rebase to push the latest changes to an existing buildpack.
launcher is an independent step that can be used to launch the application at any time.
content/docs/buildpack-basics.md
Outdated
| A platform typically refers to an organization or service provider (e.g., | ||
| kpack, Tekton, Fly.io, Digital Ocean, Google Cloud, Heroku, SalesForce, etc.) | ||
| that incorporates Buildpacks within their products to make buildpack | ||
| functionality available to their end-users (typically, application | ||
| developers). |
There was a problem hiding this comment.
In the buildpacks project we have a clear idea of what a platform is (in our platform spec). I wonder if we need to tease apart the idea of a platform and a platform oprerator in this paragraph?
There was a problem hiding this comment.
- Yeah, I wrestled with this during the first draft, I guess my over-simplification changed the meaning. How about the following:
What is a Platform:
A platform coordinates builds by invoking the lifecycle binary together with the buildpacks and the application source code in order to produce an executable OCI image.
Platform Operators
Platform Operators are organizations or service providers (e.g., kpack,
Tekton, Fly.io, Digital Ocean, Google Cloud, Heroku, SalesForce, etc.) that
incorporates Buildpacks within their products to make buildpack functionality
available to their end-users (typically, application developers).
- Added an example to BuildPack definition - rephrased Lifecycle for clarity - Rephrased Platorm and Platform Operators for clarity
|
Thanks @AidanDelaney for the quick review. Please see if the recent changes make sense. I'll connect on Slack as well 👍 |
|
Hello @AidanDelaney I had some pending notes on this topic (source), so I thought I'd whip them up into a couple of diagrams to see if the article can be made useful as a whole. Here's how the new section looks:
|
Hello Buildpackers!
I was going through the documentation (to familiarize myself for GSoD) and thought that an early intro to some things would have helped my user journey better.
Need for this change
The introductory documentation does little to explain the basic terminology that is used in it.
For example, the App Journey tutorial (https://buildpacks.io/docs/app-journey/) has a heading: "What is a Buildpack?", but it doesn't clearly define a buildpack (it gushes over how 'quick', 'quite' and 'transformational' it is).
While I like the gradual approach of introducing terminology as it is encountered, I think the writeup suffers from the 'Curse of Knowledge'. The writer has an image that comes to their mind when they think 'buildpack', or 'lifecycle', but for a new reader, these are just generic words and it takes a while for a user to be able to instinctively visualize the terminology where they encounter it.
Testing
I have installed Hugo and tested how this looks on local server (image attached below).