hazza/docker-stacks
1
0
Fork 0
mirror of https://github.com/jupyter/docker-stacks.git synced 2025-10-18 07:22:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Travis -> GitHub Actions in doc

Browse Source
This commit is contained in:
Peter Parente
2020-08-07 21:56:05 -04:00
parent 2db6171566
commit 95f792c690
6 changed files with 347 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/contributing/features.md
View File

@@ -1,33 +1,49 @@
# New Features
Thank you for contributing to the Jupyter Docker Stacks! We review pull requests of new features (e.g., new packages, new scripts, new flags) to balance the value of the images to the Jupyter community with the cost of maintaining the images over time.
Thank you for contributing to the Jupyter Docker Stacks! We review pull requests of new features
(e.g., new packages, new scripts, new flags) to balance the value of the images to the Jupyter
community with the cost of maintaining the images over time.
## Suggesting a New Feature
Please follow the process below to suggest a new feature for inclusion in one of the core stacks:
1. [Open a GitHub issue](https://github.com/jupyter/docker-stacks/issues) describing the feature you'd like to contribute.
2. Discuss with the maintainers whether the addition makes sense in [one of the core stacks](../using/selecting.md#Core-Stacks), as a [recipe in the documentation](recipes.md), as a [community stack](stacks.md), or as something else entirely.
1. [Open a GitHub issue](https://github.com/jupyter/docker-stacks/issues) describing the feature
you'd like to contribute.
2. Discuss with the maintainers whether the addition makes sense in
[one of the core stacks](../using/selecting.md#Core-Stacks), as a
[recipe in the documentation](recipes.md), as a [community stack](stacks.md), or as something
else entirely.
## Selection Criteria
Roughly speaking, we evaluate new features based on the following criteria:
* **Usefulness to Jupyter users**: Is the feature generally applicable across domains? Does it work with Jupyter Notebook, JupyterLab, JupyterHub, etc.?
* **Fit with the image purpose**: Does the feature match the theme of the stack in which it will be added? Would it fit better in a new, community stack?
* **Complexity of build / runtime configuration**: How many lines of code does the feature require in one of the Dockerfiles or startup scripts? Does it require new scripts entirely? Do users need to adjust how they use the images?
* **Impact on image metrics**: How many bytes does the feature and its dependencies add to the image(s)? How many minutes do they add to the build time?
* **Ability to support the addition**: Can existing maintainers answer user questions and address future build issues? Are the contributors interested in helping with long-term maintenance? Can we write tests to ensure the feature continues to work over time?
- **Usefulness to Jupyter users**: Is the feature generally applicable across domains? Does it work
with Jupyter Notebook, JupyterLab, JupyterHub, etc.?
- **Fit with the image purpose**: Does the feature match the theme of the stack in which it will be
added? Would it fit better in a new, community stack?
- **Complexity of build / runtime configuration**: How many lines of code does the feature require
in one of the Dockerfiles or startup scripts? Does it require new scripts entirely? Do users need
to adjust how they use the images?
- **Impact on image metrics**: How many bytes does the feature and its dependencies add to the
image(s)? How many minutes do they add to the build time?
- **Ability to support the addition**: Can existing maintainers answer user questions and address
future build issues? Are the contributors interested in helping with long-term maintenance? Can we
write tests to ensure the feature continues to work over time?
## Submitting a Pull Request
If there's agreement that the feature belongs in one or more of the core stacks:
1. Implement the feature in a local clone of the `jupyter/docker-stacks` project.
2. Please build the image locally before submitting a pull request. Building the image locally shortens the debugging cycle by taking some load off [Travis CI](http://travis-ci.org/), which graciously provides free build services for open source projects like this one. If you use `make`, call:
```bash
make build/somestack-notebook
```
3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
4. Watch for Travis to report a build success or failure for your PR on GitHub.
2. Please build the image locally before submitting a pull request. Building the image locally
shortens the debugging cycle by taking some load off GitHub Actions, which graciously provide
free build services for open source projects like this one. If you use `make`, call:
```bash
make build/somestack-notebook
```
3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)
(PR) with your changes.
4. Watch for GitHub to report a build success or failure for your PR on GitHub.
5. Discuss changes with the maintainers and address any build issues.

38
docs/contributing/packages.md
View File

@@ -1,29 +1,41 @@
# Package Updates
We actively seek pull requests which update packages already included in the project Dockerfiles. This is a great way for first-time contributors to participate in developing the Jupyter Docker Stacks.
We actively seek pull requests which update packages already included in the project Dockerfiles.
This is a great way for first-time contributors to participate in developing the Jupyter Docker
Stacks.
Please follow the process below to update a package version:
1. Locate the Dockerfile containing the library you wish to update (e.g., [base-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/base-notebook/Dockerfile), [scipy-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/scipy-notebook/Dockerfile))
2. Adjust the version number for the package. We prefer to pin the major and minor version number of packages so as to minimize rebuild side-effects when users submit pull requests (PRs). For example, you'll find the Jupyter Notebook package, `notebook`, installed using conda with `notebook=5.4.*`.
3. Please build the image locally before submitting a pull request. Building the image locally shortens the debugging cycle by taking some load off [Travis CI](http://travis-ci.org/), which graciously provides free build services for open source projects like this one. If you use `make`, call:
```bash
make build/somestack-notebook
```
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
5. Watch for Travis to report a build success or failure for your PR on GitHub.
6. Discuss changes with the maintainers and address any build issues. Version conflicts are the most common problem. You may need to upgrade additional packages to fix build failures.
1. Locate the Dockerfile containing the library you wish to update (e.g.,
[base-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/base-notebook/Dockerfile),
[scipy-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/scipy-notebook/Dockerfile))
2. Adjust the version number for the package. We prefer to pin the major and minor version number of
packages so as to minimize rebuild side-effects when users submit pull requests (PRs). For
example, you'll find the Jupyter Notebook package, `notebook`, installed using conda with
`notebook=5.4.*`.
3. Please build the image locally before submitting a pull request. Building the image locally
shortens the debugging cycle by taking some load off GitHub Actions, which graciously provide
free build services for open source projects like this one. If you use `make`, call:
```bash
make build/somestack-notebook
```
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)
(PR) with your changes.
5. Watch for GitHub to report a build success or failure for your PR on GitHub.
6. Discuss changes with the maintainers and address any build issues. Version conflicts are the most
common problem. You may need to upgrade additional packages to fix build failures.
## Notes
In order to help identifying packages that can be updated you can use the following helper tool.
It will list all the packages installed in the `Dockerfile` that can be updated -- dependencies are filtered to focus only on requested packages.
In order to help identifying packages that can be updated you can use the following helper tool. It
will list all the packages installed in the `Dockerfile` that can be updated -- dependencies are
filtered to focus only on requested packages.
```bash
$ make check-outdated/base-notebook
# INFO test_outdated:test_outdated.py:80 3/8 (38%) packages could be updated
# INFO test_outdated:test_outdated.py:82
# INFO test_outdated:test_outdated.py:82
# Package Current Newest
# ---------- --------- --------
# conda 4.7.12 4.8.2

104
docs/contributing/stacks.md
View File

@@ -1,13 +1,20 @@
# Community Stacks
We love to see the community create and share new Jupyter Docker images. We've put together a [cookiecutter project](https://github.com/jupyter/cookiecutter-docker-stacks) and the documentation below to help you get started defining, building, and sharing your Jupyter environments in Docker. Following these steps will:
We love to see the community create and share new Jupyter Docker images. We've put together a
[cookiecutter project](https://github.com/jupyter/cookiecutter-docker-stacks) and the documentation
below to help you get started defining, building, and sharing your Jupyter environments in Docker.
Following these steps will:
1. Setup a project on GitHub containing a Dockerfile based on either the `jupyter/base-notebook` or `jupyter/minimal-notebook` image.
2. Configure Travis CI to build and test your image when users submit pull requests to your repository.
1. Setup a project on GitHub containing a Dockerfile based on either the `jupyter/base-notebook` or
`jupyter/minimal-notebook` image.
2. Configure GitHub Actions to build and test your image when users submit pull requests to your
repository.
3. Configure Docker Cloud to build and host your images for others to use.
4. Update the [list of community stacks](../using/selecting.html#community-stacks) in this documentation to include your image.
4. Update the [list of community stacks](../using/selecting.html#community-stacks) in this
documentation to include your image.
This approach mirrors how we build and share the core stack images. Feel free to follow it or pave your own path using alternative services and build tools.
This approach mirrors how we build and share the core stack images. Feel free to follow it or pave
your own path using alternative services and build tools.
## Creating a Project
@@ -17,29 +24,31 @@ First, install [cookiecutter](https://github.com/audreyr/cookiecutter) using pip
pip install cookiecutter # or conda install cookiecutter
```
Run the cookiecutter command pointing to the [jupyter/cookiecutter-docker-stacks](https://github.com/jupyter/cookiecutter-docker-stacks) project on GitHub.
Run the cookiecutter command pointing to the
[jupyter/cookiecutter-docker-stacks](https://github.com/jupyter/cookiecutter-docker-stacks) project
on GitHub.
```bash
cookiecutter https://github.com/jupyter/cookiecutter-docker-stacks.git
```
Enter a name for your new stack image. This will serve as both the git repository
name and the part of the Docker image name after the slash.
Enter a name for your new stack image. This will serve as both the git repository name and the part
of the Docker image name after the slash.
```
stack_name [my-jupyter-stack]:
```
Enter the user or organization name under which this stack will reside on
Docker Cloud / Hub. You must have access to manage this Docker Cloud org in
order to push images here and setup automated builds.
Enter the user or organization name under which this stack will reside on Docker Cloud / Hub. You
must have access to manage this Docker Cloud org in order to push images here and setup automated
builds.
```
stack_org [my-project]:
```
Select an image from the jupyter/docker-stacks project that will serve as the
base for your new image.
Select an image from the jupyter/docker-stacks project that will serve as the base for your new
image.
```
stack_base_image [jupyter/base-notebook]:
@@ -65,47 +74,66 @@ git push -u origin master
## Configuring Travis
Next, link your GitHub project to Travis CI to build your Docker image whenever you or someone else submits a pull request.
> NOTE: This section and the cookiecutter template should be updated to describe using GitHub
> Actions now that jupyter/docker-stacks uses that service.
1. Visit [https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI](https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI) and follow the instructions to add the Travis CI application to your GitHub account.
3. Visit [https://travis-ci.org](https://travis-ci.org).
4. Click the + symbol at the top of the left sidebar.
![Travis sidebar with plus button screenshot](../_static/travis-plus-repo.png)
5. Locate your project repository either in your primary user account or in one of the organizations to which you belong.
6. Click the toggle to enable builds for the project repository.
7. Click the **Settings** button for that repository.
![Travis enable build toggle screenshot](../_static/travis-enable-build.png)
8. Enable **Build only if .travis.yml is present** and **Build pushed pull requests**.
![Travis build settings screenshot](../_static/travis-build-settings.png)
9. Disable **Build pushed branches**.
Next, link your GitHub project to Travis CI to build your Docker image whenever you or someone else
submits a pull request.
1. Visit
[https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI](https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI)
and follow the instructions to add the Travis CI application to your GitHub account.
2. Visit [https://travis-ci.org](https://travis-ci.org).
3. Click the + symbol at the top of the left sidebar.
![Travis sidebar with plus button screenshot](../_static/travis-plus-repo.png)
4. Locate your project repository either in your primary user account or in one of the organizations
to which you belong.
5. Click the toggle to enable builds for the project repository.
6. Click the **Settings** button for that repository.
![Travis enable build toggle screenshot](../_static/travis-enable-build.png)
7. Enable **Build only if .travis.yml is present** and **Build pushed pull requests**.
![Travis build settings screenshot](../_static/travis-build-settings.png)
8. Disable **Build pushed branches**.
## Configuring Docker Cloud
Now, configure Docker Cloud to build your stack image and push it to Docker Hub repository whenever you merge a GitHub pull request to the master branch of your project.
Now, configure Docker Cloud to build your stack image and push it to Docker Hub repository whenever
you merge a GitHub pull request to the master branch of your project.
1. Visit [https://cloud.docker.com/](https://cloud.docker.com/) and login.
2. Select the account or organization matching the one you entered when prompted with `stack_org` by the cookiecutter.
![Docker account selection screenshot](../_static/docker-org-select.png)
2. Select the account or organization matching the one you entered when prompted with `stack_org` by
the cookiecutter. ![Docker account selection screenshot](../_static/docker-org-select.png)
3. Scroll to the bottom of the page and click **Create repository**.
4. Enter the name of the image matching the one you entered when prompted with `stack_name` by the cookiecutter.
![Docker image name and description screenshot](../_static/docker-repo-name.png)
4. Enter the name of the image matching the one you entered when prompted with `stack_name` by the
cookiecutter. ![Docker image name and description screenshot](../_static/docker-repo-name.png)
5. Enter a description for your image.
6. Click **GitHub** under the **Build Settings** and follow the prompts to connect your account if it is not already connected.
7. Select the GitHub organization and repository containing your image definition from the dropdowns.
![Docker from GitHub automated build screenshot](../_static/docker-github-settings.png)
6. Click **GitHub** under the **Build Settings** and follow the prompts to connect your account if
it is not already connected.
7. Select the GitHub organization and repository containing your image definition from the
dropdowns.
![Docker from GitHub automated build screenshot](../_static/docker-github-settings.png)
8. Click the **Create and Build** button.
## Defining Your Image
Make edits the Dockerfile in your project to add third-party libraries and configure Jupyter applications. Refer to the Dockerfiles for the core stacks (e.g., [jupyter/datascience-notebook](https://github.com/jupyter/docker-stacks/blob/master/datascience-notebook/Dockerfile)) to get a feel for what's possible and best practices.
Make edits the Dockerfile in your project to add third-party libraries and configure Jupyter
applications. Refer to the Dockerfiles for the core stacks (e.g.,
[jupyter/datascience-notebook](https://github.com/jupyter/docker-stacks/blob/master/datascience-notebook/Dockerfile))
to get a feel for what's possible and best practices.
[Submit pull requests](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) to your project repository on GitHub. Ensure your image builds properly on Travis before merging to master. Refer to Docker Cloud for builds of your master branch that you can `docker pull`.
[Submit pull requests](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)
to your project repository on GitHub. Ensure your image builds properly on Travis before merging to
master. Refer to Docker Cloud for builds of your master branch that you can `docker pull`.
## Sharing Your Image
Finally, if you'd like to add a link to your project to this documentation site, please do the following:
Finally, if you'd like to add a link to your project to this documentation site, please do the
following:
1. Clone ths [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks) GitHub repository.
2. Open the `docs/using/selecting.md` source file and locate the **Community Stacks** section.
3. Add a bullet with a link to your project and a short description of what your Docker image contains.
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. Maintainers will respond and work with you to address any formatting or content issues.
3. Add a bullet with a link to your project and a short description of what your Docker image
contains.
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)
(PR) with your changes. Maintainers will respond and work with you to address any formatting or
content issues.

33
docs/contributing/tests.md
View File

@@ -1,22 +1,33 @@
# Image Tests
We greatly appreciate pull requests that extend the automated tests that vet the basic functionality of the Docker images.
We greatly appreciate pull requests that extend the automated tests that vet the basic functionality
of the Docker images.
## How the Tests Work
Travis executes `make build-test-all` against pull requests submitted to the `jupyter/docker-stacks` repository. This `make` command builds every docker image. After building each image, the `make` command executes `pytest` to run both image-specific tests like those in [base-notebook/test/](https://github.com/jupyter/docker-stacks/tree/master/base-notebook/test) and common tests defined in [test/](https://github.com/jupyter/docker-stacks/tree/master/test). Both kinds of tests make use of global [pytest fixtures](https://docs.pytest.org/en/latest/fixture.html) defined in the [conftest.py](https://github.com/jupyter/docker-stacks/blob/master/conftest.py) file at the root of the projects.
GitHub executes `make build-test-all` against pull requests submitted to the `jupyter/docker-stacks`
repository. This `make` command builds every docker image. After building each image, the `make`
command executes `pytest` to run both image-specific tests like those in
[base-notebook/test/](https://github.com/jupyter/docker-stacks/tree/master/base-notebook/test) and
common tests defined in [test/](https://github.com/jupyter/docker-stacks/tree/master/test). Both
kinds of tests make use of global [pytest fixtures](https://docs.pytest.org/en/latest/fixture.html)
defined in the [conftest.py](https://github.com/jupyter/docker-stacks/blob/master/conftest.py) file
at the root of the projects.
## Contributing New Tests
Please follow the process below to add new tests:
1. If the test should run against every image built, add your test code to one of the modules in [test/](https://github.com/jupyter/docker-stacks/tree/master/test) or create a new module.
2. If your test should run against a single image, add your test code to one of the modules in `some-notebook/test/` or create a new module.
1. If the test should run against every image built, add your test code to one of the modules in
[test/](https://github.com/jupyter/docker-stacks/tree/master/test) or create a new module.
2. If your test should run against a single image, add your test code to one of the modules in
`some-notebook/test/` or create a new module.
3. Build one or more images you intend to test and run the tests locally. If you use `make`, call:
```bash
make build/somestack-notebook
make test/somestack-notebook
```
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
5. Watch for Travis to report a build success or failure for your PR on GitHub.
6. Discuss changes with the maintainers and address any issues running the tests on Travis.
```bash
make build/somestack-notebook
make test/somestack-notebook
```
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)
(PR) with your changes.
5. Watch for GitHub to report a build success or failure for your PR on GitHub.
6. Discuss changes with the maintainers and address any issues running the tests on GitHub.