Skip to content

Commit bc90b0f

Browse files
BRONSOLOBRONSOLO
authored
Merge pull request #9 from plotly/doc-upstream-flow
add upstream / new readmes
2 parents 0f7eadc + 30194ea commit bc90b0f

File tree

2 files changed

+151
-132
lines changed

2 files changed

+151
-132
lines changed

‎README-upstream.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Paketo Buildpack for CPython Cloud Native
2+
The CPython Buildpack provides CPython (reference implementation of Python) 3.
3+
The buildpack installs CPython onto the `$PATH` which makes it available for
4+
subsequent buildpacks and in the final running container. It also sets the
5+
`$PYTHONPATH` environment variable for subsequent buildpacks and launch-time
6+
processes.
7+
8+
The buildpack is published for consumption at `gcr.io/paketo-buildpacks/cpython` and
9+
`paketobuildpacks/cpython`.
10+
11+
## Behavior
12+
13+
This buildpack always participates.
14+
15+
### Build time
16+
This buildpack performs the following actions at build time:
17+
* Contributes `cpython` to a layer - either via a precompiled dependency or by
18+
compiling from source.
19+
* Python is precompiled for recognized, supported stacks (currently the Ubuntu-based stacks)
20+
* Python is compiled from source during the build phase for unrecognized stacks.
21+
* [dependency/](dependency/README.md) contains more information how cpython is built.
22+
* Sets the `PYTHONPYCACHEPREFIX` environment variable to the `/tmp` directory
23+
for this and any subsequent buildpacks.
24+
* This effectively disables the `__pycache__` directories, in turn enabling
25+
reproducible builds.
26+
* It can be overridden via standard means (e.g. `pack build --env
27+
"PYTHONPYCACHEPREFIX=/some/other/dir"`) if there is a need to keep the
28+
`__pycache__` directories in place of reproducible builds.
29+
* Sets the `PYTHONPATH` to the `cpython` layer path for this and any subsequent
30+
buildpacks.
31+
* Adds the newly installed `cpython` bin dir location to the `PATH`.
32+
33+
### Launch time
34+
This buildpack does the following at launch time:
35+
36+
* Sets a default value for the `PYTHONPATH` environment variable.
37+
38+
## Configuration
39+
40+
### `BP_CPYTHON_VERSION`
41+
The `BP_CPYTHON_VERSION` variable allows you to specify the version of CPython
42+
that is installed. (Available versions can be found in the
43+
[buildpack.toml](./buildpack.toml).)
44+
45+
#### `pack build` flag
46+
```shell
47+
pack build my-app --env BP_CPYTHON_VERSION=3.10.*
48+
```
49+
50+
#### In a [`project.toml`](https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md)
51+
```toml
52+
[build]
53+
[[build.env]]
54+
name = 'BP_CPYTHON_VERSION'
55+
value = '3.10.*' # any valid semver constraints (e.g. 3.10.2, 3.*) are acceptable
56+
```
57+
58+
### `BP_CPYTHON_CONFIGURE_FLAGS`
59+
The `BP_CPYTHON_CONFIGURE_FLAGS` variable allows you to specify configure flags
60+
when python is installed from source. This is only applicable when using custom
61+
stacks. Paketo stacks such as `io.buildpacks.stacks.bionic` install pre-built binaries.
62+
63+
* The format is space-separated strings, and they are passed directly to the
64+
`cpython` `./configure` process , e.g. `--foo --bar=baz`.
65+
* See [python documentation](https://docs.python.org/3/using/configure.html) for supported flags.
66+
* Default flags if not specified: `--with-ensurepip`
67+
* Note that default flags are overridden if you specify this environment variable,
68+
which means you almost certainly want to include the defaults along with any custom flags.
69+
- e.g. `--with-ensurepip --foo --bar=baz`
70+
71+
### `BP_LOG_LEVEL`
72+
The `BP_LOG_LEVEL` flag controls the level of verbosity of the buildpack output logs.
73+
For more detail, set it to `debug`.
74+
75+
For example, when compiling from source, setting `BP_LOG_LEVEL=debug` shows the
76+
commands and outputs run to build python.
77+
78+
## Integration
79+
80+
The CPython Buildpack provides `cpython` as a dependency. Downstream
81+
buildpacks, can require the cpython dependency by generating [Build Plan
82+
TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
83+
file that looks like the following:
84+
85+
```toml
86+
[[requires]]
87+
# The name of the CPython dependency is "cpython". This value is considered
88+
# part of the public API for the buildpack and will not change without a plan
89+
# for deprecation.
90+
name = "cpython"
91+
92+
# The CPython buildpack supports some non-required metadata options.
93+
[requires.metadata]
94+
95+
# The version of the CPython dependency is not required. In the case it
96+
# is not specified, the buildpack will provide the default version, which can
97+
# be seen in the buildpack.toml file.
98+
# If you wish to request a specific version, the buildpack supports
99+
# specifying a semver constraint in the form of "3.*", "3.10.*", or even
100+
# "3.10.2".
101+
version = "3.10.2"
102+
103+
# Setting the build flag to true will ensure that the CPython
104+
# depdendency is available on the $PATH for subsequent buildpacks during
105+
# their build phase. If you are writing a buildpack that needs to use CPython
106+
# during its build process, this flag should be set to true.
107+
build = true
108+
109+
# Setting the launch flag to true will ensure that cpython is
110+
# available to the running application. If you are writing an application
111+
# that needs to run cpython at runtime, this flag should be set to true.
112+
launch = true
113+
```
114+
115+
## Usage
116+
117+
To package this buildpack for consumption:
118+
119+
```
120+
$ ./scripts/package.sh --version <version-number>
121+
```
122+
123+
This will create a `buildpackage.cnb` file under the `build` directory which you
124+
can use to build your app as follows:
125+
`pack build <app-name> -p <path-to-app> -b build/buildpackage.cnb -b <other-buildpacks..>`
126+
127+
To run the unit and integration tests for this buildpack:
128+
```
129+
$ ./scripts/unit.sh && ./scripts/integration.sh
130+
```
131+
132+
## Compatibility
133+
134+
This buildpack is currently only supported on linux distributions.
135+
136+
Pre-compiled distributions of Python are provided for the Paketo stacks (i.e.
137+
`io.buildpacks.stack.jammy` and `io.buildpacks.stacks.bionic`).
138+
139+
Source distributions of Python are provided for all other linux stacks.

‎README.md

Lines changed: 12 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,19 @@
11
# Paketo Buildpack for CPython Cloud Native
2-
The CPython Buildpack provides CPython (reference implementation of Python) 3.
3-
The buildpack installs CPython onto the `$PATH` which makes it available for
4-
subsequent buildpacks and in the final running container. It also sets the
5-
`$PYTHONPATH` environment variable for subsequent buildpacks and launch-time
6-
processes.
72

8-
The buildpack is published for consumption at `gcr.io/paketo-buildpacks/cpython` and
9-
`paketobuildpacks/cpython`.
3+
A copy of the upstream README.md can be found here: [README-upstream.md](README-upstream.md)
104

11-
## Behavior
5+
# Plotly Branches
126

13-
This buildpack always participates.
7+
- The `main-upstream` branch of this repository is used to sync in the `main` branch of the upstream as its source. It does not contain any custom Plotly code changes
8+
- The `main` branch of this repository is used to be the most up to date branch containing custom Plotly code changes
9+
- The `XY-release` branches of this repository are made off of the `main` branch as part of our code freeze process: [DE Release Guide](https://plotly.atlassian.net/wiki/x/doAbH)
1410

15-
### Build time
16-
This buildpack performs the following actions at build time:
17-
* Contributes `cpython` to a layer - either via a precompiled dependency or by
18-
compiling from source.
19-
* Python is precompiled for recognized, supported stacks (currently the Ubuntu-based stacks)
20-
* Python is compiled from source during the build phase for unrecognized stacks.
21-
* [dependency/](dependency/README.md) contains more information how cpython is built.
22-
* Sets the `PYTHONPYCACHEPREFIX` environment variable to the `/tmp` directory
23-
for this and any subsequent buildpacks.
24-
* This effectively disables the `__pycache__` directories, in turn enabling
25-
reproducible builds.
26-
* It can be overridden via standard means (e.g. `pack build --env
27-
"PYTHONPYCACHEPREFIX=/some/other/dir"`) if there is a need to keep the
28-
`__pycache__` directories in place of reproducible builds.
29-
* Sets the `PYTHONPATH` to the `cpython` layer path for this and any subsequent
30-
buildpacks.
31-
* Adds the newly installed `cpython` bin dir location to the `PATH`.
11+
# Plotly Release Flow
3212

33-
### Launch time
34-
This buildpack does the following at launch time:
13+
- All PRs (other than an upstream sync detailed below) should first land on `main`
14+
- If a PR is needed for a given release, a new PR should be made against that release branch
15+
- When needing to pull in upstream changes (typically done as a post-release task to stay up to date as needed):
16+
- Navigate the the [main-upstream](https://github.com/plotly/paketo-buildpacks_cpython/tree/main-upstream) branch
17+
- Select **Sync fork**
18+
- A PR should then be opened to add these changes to our `main` branch, favouring our custom work whenever there are conflicts
3519

36-
* Sets a default value for the `PYTHONPATH` environment variable.
37-
38-
## Configuration
39-
40-
### `BP_CPYTHON_VERSION`
41-
The `BP_CPYTHON_VERSION` variable allows you to specify the version of CPython
42-
that is installed. (Available versions can be found in the
43-
[buildpack.toml](./buildpack.toml).)
44-
45-
#### `pack build` flag
46-
```shell
47-
pack build my-app --env BP_CPYTHON_VERSION=3.10.*
48-
```
49-
50-
#### In a [`project.toml`](https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md)
51-
```toml
52-
[build]
53-
[[build.env]]
54-
name = 'BP_CPYTHON_VERSION'
55-
value = '3.10.*' # any valid semver constraints (e.g. 3.10.2, 3.*) are acceptable
56-
```
57-
58-
### `BP_CPYTHON_CONFIGURE_FLAGS`
59-
The `BP_CPYTHON_CONFIGURE_FLAGS` variable allows you to specify configure flags
60-
when python is installed from source. This is only applicable when using custom
61-
stacks. Paketo stacks such as `io.buildpacks.stacks.bionic` install pre-built binaries.
62-
63-
* The format is space-separated strings, and they are passed directly to the
64-
`cpython` `./configure` process , e.g. `--foo --bar=baz`.
65-
* See [python documentation](https://docs.python.org/3/using/configure.html) for supported flags.
66-
* Default flags if not specified: `--with-ensurepip`
67-
* Note that default flags are overridden if you specify this environment variable,
68-
which means you almost certainly want to include the defaults along with any custom flags.
69-
- e.g. `--with-ensurepip --foo --bar=baz`
70-
71-
### `BP_LOG_LEVEL`
72-
The `BP_LOG_LEVEL` flag controls the level of verbosity of the buildpack output logs.
73-
For more detail, set it to `debug`.
74-
75-
For example, when compiling from source, setting `BP_LOG_LEVEL=debug` shows the
76-
commands and outputs run to build python.
77-
78-
## Integration
79-
80-
The CPython Buildpack provides `cpython` as a dependency. Downstream
81-
buildpacks, can require the cpython dependency by generating [Build Plan
82-
TOML](https://github.com/buildpacks/spec/blob/master/buildpack.md#build-plan-toml)
83-
file that looks like the following:
84-
85-
```toml
86-
[[requires]]
87-
# The name of the CPython dependency is "cpython". This value is considered
88-
# part of the public API for the buildpack and will not change without a plan
89-
# for deprecation.
90-
name = "cpython"
91-
92-
# The CPython buildpack supports some non-required metadata options.
93-
[requires.metadata]
94-
95-
# The version of the CPython dependency is not required. In the case it
96-
# is not specified, the buildpack will provide the default version, which can
97-
# be seen in the buildpack.toml file.
98-
# If you wish to request a specific version, the buildpack supports
99-
# specifying a semver constraint in the form of "3.*", "3.10.*", or even
100-
# "3.10.2".
101-
version = "3.10.2"
102-
103-
# Setting the build flag to true will ensure that the CPython
104-
# depdendency is available on the $PATH for subsequent buildpacks during
105-
# their build phase. If you are writing a buildpack that needs to use CPython
106-
# during its build process, this flag should be set to true.
107-
build = true
108-
109-
# Setting the launch flag to true will ensure that cpython is
110-
# available to the running application. If you are writing an application
111-
# that needs to run cpython at runtime, this flag should be set to true.
112-
launch = true
113-
```
114-
115-
## Usage
116-
117-
To package this buildpack for consumption:
118-
119-
```
120-
$ ./scripts/package.sh --version <version-number>
121-
```
122-
123-
This will create a `buildpackage.cnb` file under the `build` directory which you
124-
can use to build your app as follows:
125-
`pack build <app-name> -p <path-to-app> -b build/buildpackage.cnb -b <other-buildpacks..>`
126-
127-
To run the unit and integration tests for this buildpack:
128-
```
129-
$ ./scripts/unit.sh && ./scripts/integration.sh
130-
```
131-
132-
## Compatibility
133-
134-
This buildpack is currently only supported on linux distributions.
135-
136-
Pre-compiled distributions of Python are provided for the Paketo stacks (i.e.
137-
`io.buildpacks.stack.jammy` and `io.buildpacks.stacks.bionic`).
138-
139-
Source distributions of Python are provided for all other linux stacks.

0 commit comments

Comments
 (0)