From ae3aeb6dc5dd6deee6d663b7088eb74d225a815f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 31 Oct 2022 22:40:52 +0000 Subject: [PATCH] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .github/ISSUE_TEMPLATE/bug_report.md | 20 ++++--- .github/ISSUE_TEMPLATE/feature_request.md | 18 +++--- .github/ISSUE_TEMPLATE/support-question.md | 7 +-- CONTRIBUTING.md | 23 ++++---- README.md | 7 +-- docs/source/architecture.md | 14 ++--- docs/source/contributing/contributing.md | 66 +++++++++++----------- docs/source/contributing/roadmap.md | 47 ++++++++------- docs/source/contributing/tasks.md | 39 ++++++------- docs/source/design.md | 5 +- tests/conda/README.md | 2 +- 11 files changed, 125 insertions(+), 123 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 2171bd67..548df578 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,23 +1,27 @@ --- name: Bug report about: Create a report to help us repair something that is currently broken -title: '' -labels: '' -assignees: '' - +title: "" +labels: "" +assignees: "" --- + ### Bug description + #### Expected behaviour + #### Actual behaviour + ### How to reproduce + 1. Go to '...' @@ -26,9 +30,9 @@ assignees: '' 4. See error ### Your personal set up + - - OS: [e.g. linux, OSX] - - Docker version: `docker version` - - repo2docker version `repo2docker --version` - +- OS: [e.g. linux, OSX] +- Docker version: `docker version` +- repo2docker version `repo2docker --version` diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 833ba6e5..a0bcd5a2 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,29 +1,29 @@ --- name: Feature request about: Suggest a new feature or a big change to repo2docker -title: '' -labels: 'needs: discussion' -assignees: '' - +title: "" +labels: "needs: discussion" +assignees: "" --- + ### Proposed change + - ### Alternative options + - ### Who would use this feature? + - ### How much effort will adding it take? + - ### Who can do this work? - + diff --git a/.github/ISSUE_TEMPLATE/support-question.md b/.github/ISSUE_TEMPLATE/support-question.md index bf10a69a..e7b543e5 100644 --- a/.github/ISSUE_TEMPLATE/support-question.md +++ b/.github/ISSUE_TEMPLATE/support-question.md @@ -1,10 +1,9 @@ --- name: Support question about: Ask a question about using repo2docker -title: '' -labels: '' -assignees: '' - +title: "" +labels: "" +assignees: "" --- 🚨 Please do **not** open an issue for support questions. Instead please search for similar issues or post on http://discourse.jupyter.org/c/questions. 🚨 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1a583d5..1dfc1957 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,19 +8,20 @@ The repo2docker developer documentation is all rendered on our documentation web If you're here, you're probably looking for the [Contributing to repo2docker development](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html) page. Please make sure you've read the following sections before opening an issue/pull request: -* [Process for making a contribution](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#process-for-making-a-contribution). - * These steps talk you through choosing the right issue template (bug report or feature request) and making a change. -* [Guidelines to getting a Pull Request merged](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#guidelines-to-getting-a-pull-request-merged). - * These are tips and tricks to help make your contribution as smooth as possible for you and for the repo2docker maintenance team. + +- [Process for making a contribution](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#process-for-making-a-contribution). + - These steps talk you through choosing the right issue template (bug report or feature request) and making a change. +- [Guidelines to getting a Pull Request merged](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#guidelines-to-getting-a-pull-request-merged). + - These are tips and tricks to help make your contribution as smooth as possible for you and for the repo2docker maintenance team. There are a few other pages to highlight: -* [Our roadmap](https://repo2docker.readthedocs.io/en/latest/contributing/roadmap.html) - * We use the roadmap to develop a shared understanding of the project's vision and direction amongst the community of users, contributors, and maintainers. +- [Our roadmap](https://repo2docker.readthedocs.io/en/latest/contributing/roadmap.html) + - We use the roadmap to develop a shared understanding of the project's vision and direction amongst the community of users, contributors, and maintainers. This is a great place to get a feel for what the maintainers are thinking about for the short, medium, and long term future of the project. -* [Design of repo2docker](https://repo2docker.readthedocs.io/en/latest/design.html) - * This page explains some of the design principles behind repo2docker. +- [Design of repo2docker](https://repo2docker.readthedocs.io/en/latest/design.html) + - This page explains some of the design principles behind repo2docker. Its a good place to understand _why_ the team have made the decisions that they have along the way! - * We absolutely encourage discussion around refactoring, updating or extending repo2docker, but please make sure that you've understood this page before opening an issue to discuss the change you'd like to propose. -* [Common developer tasks and how-tos](https://repo2docker.readthedocs.io/en/latest/contributing/tasks.html) - * Some notes on running tests, buildpack dependencies, creating a release, and keeping the pip files up to date. + - We absolutely encourage discussion around refactoring, updating or extending repo2docker, but please make sure that you've understood this page before opening an issue to discuss the change you'd like to propose. +- [Common developer tasks and how-tos](https://repo2docker.readthedocs.io/en/latest/contributing/tasks.html) + - Some notes on running tests, buildpack dependencies, creating a release, and keeping the pip files up to date. diff --git a/README.md b/README.md index 84949e84..01d60eeb 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ For more information, please visit --- ## Using repo2docker + ### Prerequisites 1. Docker to build & run the repositories. The [community edition](https://store.docker.com/search?type=edition&offering=community) @@ -83,21 +84,19 @@ something like: If you copy paste that URL into your browser you will see a Jupyter Notebook with the contents of the repository you had just built! -For more information on how to use ``repo2docker``, see the +For more information on how to use `repo2docker`, see the [usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html). - ## Repository specifications Repo2Docker looks for configuration files in the source repository to determine how the Docker image should be built. For a list of the configuration -files that ``repo2docker`` can use, see the +files that `repo2docker` can use, see the [complete list of configuration files](https://repo2docker.readthedocs.io/en/latest/config_files.html). The philosophy of repo2docker is inspired by [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks). - ## Docker Image Repo2Docker can be run inside a Docker container if access to the Docker Daemon is provided, for example see [BinderHub](https://github.com/jupyterhub/binderhub). Docker images are [published to quay.io](https://quay.io/repository/jupyterhub/repo2docker?tab=tags). The old [Docker Hub image](https://hub.docker.com/r/jupyter/repo2docker) is no longer supported. diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 15385518..0153c8ae 100644 --- a/docs/source/architecture.md +++ b/docs/source/architecture.md @@ -4,6 +4,7 @@ This is a living document talking about the architecture of repo2docker from various perspectives. (buildpacks)= + ## Buildpacks The **buildpack** concept comes from [Heroku](https://devcenter.heroku.com/articles/buildpacks) @@ -57,7 +58,7 @@ and basic notebook packages (from `repo2docker/buildpacks/conda/environment.yml` to be the same for most repositories built with `CondaBuildPack`, so we want to use [docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as much as possible for performance reasons. Next time a repository is built with `CondaBuildPack`, -we can skip straight to the **copy** step (since the base environment docker image *layers* have +we can skip straight to the **copy** step (since the base environment docker image _layers_ have already been built and cached). The `get_build_scripts` and `get_build_script_files` methods are primarily used for this. @@ -65,11 +66,11 @@ The `get_build_scripts` and `get_build_script_files` methods are primarily used and `get_build_script_files` is used to copy specific scripts (such as a conda installer) into the image to be run as pat of `get_build_scripts`. Code in either has following constraints: -1. You can *not* use the contents of repository in them, since this happens before the repository +1. You can _not_ use the contents of repository in them, since this happens before the repository is copied into the image. For example, `pip install -r requirements.txt` will not work, since there's no `requirements.txt` inside the image at this point. This is an explicit design decision, to enable better layer caching. -2. You *may*, however, read the contents of the repository and modify the scripts emitted based +2. You _may_, however, read the contents of the repository and modify the scripts emitted based on that! For example, in `CondaBuildPack`, if there's Python 2 specified in `environment.yml`, a different kind of environment is set up. The reading of the `environment.yml` is performed in the BuildPack itself, and not in the scripts returned by `get_build_scripts`. This is fine. @@ -118,7 +119,7 @@ a path to a repository. This might be a local path or a URL. Upon being called, `repo2docker` will loop through all ContentProviders and perform the following commands: -* Run the `detect()` method on the repository path given to `repo2docker`. This +- Run the `detect()` method on the repository path given to `repo2docker`. This should return any value other than `None` if the path matches what the ContentProvider is looking for. @@ -126,12 +127,11 @@ commands: > checks whether the argument is a valid local path. If so, then `detect(` > returns a dictionary: `{'path': source}` which defines the path to the repository. > This path is used by `fetch()` to check that it matches the output directory. -* If `detect()` returns something other than `None`, run `fetch()` with the + +- If `detect()` returns something other than `None`, run `fetch()` with the returned value as its argument. This should result in the contents of the repository being placed locally to a folder. For more information on ContentProviders, take a look at [the ContentProvider base class](https://github.com/jupyterhub/repo2docker/blob/80b979f8580ddef184d2ba7d354e7a833cfa38a4/repo2docker/contentproviders/base.py#L16-L60) which has more explanation. - - diff --git a/docs/source/contributing/contributing.md b/docs/source/contributing/contributing.md index 7d101dfe..8e26bcda 100644 --- a/docs/source/contributing/contributing.md +++ b/docs/source/contributing/contributing.md @@ -2,33 +2,33 @@ Thank you for thinking about contributing to repo2docker! This is an open source project that is developed and maintained entirely by volunteers. -*Your contribution* is integral to the future of the project. +_Your contribution_ is integral to the future of the project. THANK YOU! ## Types of contribution There are many ways to contribute to repo2docker: -* **Update the documentation.** +- **Update the documentation.** If you're reading a page or docstring and it doesn't make sense (or doesn't exist!), please let us know by opening a bug report. It's even more amazing if you can give us a suggested change. -* **Fix bugs or add requested features.** +- **Fix bugs or add requested features.** Have a look through the [issue tracker](https://github.com/jupyterhub/repo2docker/issues) and see if there are any tagged as ["help wanted"](https://github.com/jupyterhub/repo2docker/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). As the label suggests, we'd love your help! -* **Report a bug.** +- **Report a bug.** If repo2docker isn't doing what you thought it would do then open a [bug report](https://github.com/jupyterhub/repo2docker/issues/new?template=bug_report.md). That issue template will ask you a few questions described in more detail below. -* **Suggest a new feature.** +- **Suggest a new feature.** We know that there are lots of ways to extend repo2docker! If you're interested in adding a feature then please open a [feature request](https://github.com/jupyterhub/repo2docker/issues/new?template=feature_request.md). That issue template will ask you a few questions described in detail below. -* **Review someone's Pull Request.** +- **Review someone's Pull Request.** Whenever somebody proposes changes to the repo2docker codebase, the community reviews the changes, and provides feedback, edits, and suggestions. Check out the [open pull requests](https://github.com/jupyterhub/repo2docker/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and provide feedback that helps improve the PR and get it merged. Please keep your feedback positive and constructive! -* **Tell people about repo2docker.** +- **Tell people about repo2docker.** As we said above, repo2docker is built by and for its community. If you know anyone who would like to use repo2docker, please tell them about the project! You could give a talk about it, or run a demonstration. @@ -42,31 +42,31 @@ This outlines the process for getting changes to the repo2docker project merged. 1. Identify the correct issue template: [bug report](https://github.com/jupyterhub/repo2docker/issues/new?template=bug_report.md) or [feature request](https://github.com/jupyterhub/repo2docker/issues/new?template=feature_request.md). - **Bug reports** ([examples](https://github.com/jupyterhub/repo2docker/issues?q=is%3Aissue+is%3Aopen+label%3Abug), [new issue](https://github.com/jupyterhub/repo2docker/issues/new?template=bug_report.md)) will ask you for a description of the problem, the expected behaviour, the actual behaviour, how to reproduce the problem, and your personal set up. - Bugs can include problems with the documentation, or code not running as expected. + **Bug reports** ([examples](https://github.com/jupyterhub/repo2docker/issues?q=is%3Aissue+is%3Aopen+label%3Abug), [new issue](https://github.com/jupyterhub/repo2docker/issues/new?template=bug_report.md)) will ask you for a description of the problem, the expected behaviour, the actual behaviour, how to reproduce the problem, and your personal set up. + Bugs can include problems with the documentation, or code not running as expected. - It is really important that you make it easy for the maintainers to reproduce the problem you're having. - This guide on creating a [minimal, complete and verifiable example](https://stackoverflow.com/help/mcve) is a great place to start. + It is really important that you make it easy for the maintainers to reproduce the problem you're having. + This guide on creating a [minimal, complete and verifiable example](https://stackoverflow.com/help/mcve) is a great place to start. - **Feature requests** ([examples](https://github.com/jupyterhub/repo2docker/labels/needs%3A%20discussion), [new issue](https://github.com/jupyterhub/repo2docker/issues/new?template=feature_request.md)) will ask you for the proposed change, any alternatives that you have considered, a description of who would use this feature, and a best-guess of how much work it will take and what skills are required to accomplish. + **Feature requests** ([examples](https://github.com/jupyterhub/repo2docker/labels/needs%3A%20discussion), [new issue](https://github.com/jupyterhub/repo2docker/issues/new?template=feature_request.md)) will ask you for the proposed change, any alternatives that you have considered, a description of who would use this feature, and a best-guess of how much work it will take and what skills are required to accomplish. - Very easy feature requests might be updates to the documentation to clarify steps for new users. - Harder feature requests may be to add new functionality to the project and will need more in depth discussion about who can complete and maintain the work. + Very easy feature requests might be updates to the documentation to clarify steps for new users. + Harder feature requests may be to add new functionality to the project and will need more in depth discussion about who can complete and maintain the work. - Feature requests are a great opportunity for you to advocate for the use case you're suggesting. - They help others understand how much effort it would be to integrate the work,and - if you're successful at convincing them that this effort is worth it - make it more likely that they to choose to work on it with you. + Feature requests are a great opportunity for you to advocate for the use case you're suggesting. + They help others understand how much effort it would be to integrate the work,and - if you're successful at convincing them that this effort is worth it - make it more likely that they to choose to work on it with you. 2. Open an issue. - Getting consensus with the community is a great way to save time later. + Getting consensus with the community is a great way to save time later. 3. Make edits in [your fork](https://help.github.com/en/articles/fork-a-repo) of the [repo2docker repository](https://github.com/jupyterhub/repo2docker). 4. Make a [pull request](https://help.github.com/en/articles/about-pull-requests). -Read the [next section](guidelines-to-getting-a-pull-request-merged) for guidelines for both reviewers and contributors on merging a PR. -6. Wait for a community member to merge your changes. - Remember that **someone else must merge your pull request**. - That goes for new contributors and long term maintainers alike. - Because `main` is continuously deployed to mybinder.org it is essential - that `main` is always in a deployable state. -7. (optional) Deploy a new version of repo2docker to mybinder.org by [following these steps](http://mybinder-sre.readthedocs.io/en/latest/deployment/how.html) + Read the [next section](guidelines-to-getting-a-pull-request-merged) for guidelines for both reviewers and contributors on merging a PR. +5. Wait for a community member to merge your changes. + Remember that **someone else must merge your pull request**. + That goes for new contributors and long term maintainers alike. + Because `main` is continuously deployed to mybinder.org it is essential + that `main` is always in a deployable state. +6. (optional) Deploy a new version of repo2docker to mybinder.org by [following these steps](http://mybinder-sre.readthedocs.io/en/latest/deployment/how.html) (guidelines-to-getting-a-pull-request-merged)= @@ -74,26 +74,27 @@ Read the [next section](guidelines-to-getting-a-pull-request-merged) for guideli These are not hard rules to be enforced by 🚓 but they are suggestions written by the repo2docker maintainers to help complete your contribution as smoothly as possible for both you and for them. -* **Create a PR as early as possible**, marking it with `[WIP]` while you work on it. +- **Create a PR as early as possible**, marking it with `[WIP]` while you work on it. This avoids duplicated work, lets you get high level feedback on functionality or API changes, and/or helps find collaborators to work with you. -* **Keep your PR focused.** +- **Keep your PR focused.** The best PRs solve one problem. If you end up changing multiple things, please open separate PRs for the different conceptual changes. -* **Add tests to your code.** +- **Add tests to your code.** PRs will not be merged if Travis is failing. -* **Apply [PEP8](https://www.python.org/dev/peps/pep-0008/)** as much as possible, but not too much. +- **Apply [PEP8](https://www.python.org/dev/peps/pep-0008/)** as much as possible, but not too much. If in doubt, ask. -* **Use merge commits** instead of merge-by-squashing/-rebasing. +- **Use merge commits** instead of merge-by-squashing/-rebasing. This makes it easier to find all changes since the last deployment `git log --merges --pretty=format:"%h %<(10,trunc)%an %<(15)%ar %s" ..` and your PR easier to review. -* **Make it clear when your PR is ready for review.** +- **Make it clear when your PR is ready for review.** Prefix the title of your pull request (PR) with `[MRG]` if the contribution is complete and should be subjected to a detailed review. -* **Use commit messages to describe _why_ you are proposing the changes you are proposing.** -* **Try to not rush changes** (the definition of rush depends on how big your changes are). +- **Use commit messages to describe _why_ you are proposing the changes you are proposing.** +- **Try to not rush changes** (the definition of rush depends on how big your changes are). Remember that everyone in the repo2docker team is a volunteer and we can not (nor would we want to) control their time or interests. Wait patiently for a reviewer to merge the PR. (Remember that **someone else** must merge your PR, even if you have the admin rights to do so.) (contributing:local-dev)= + ## Setting up for Local Development To develop & test repo2docker locally, you need: @@ -149,7 +150,6 @@ according to black's style guide. You can activate it with `pre-commit install`. As part of our continuous integration tests we will check that code is formatted properly and the tests will fail if this is not the case. - ### Verify that docker is installed and running If you do not already have [Docker](https://www.docker.com/), you should be able diff --git a/docs/source/contributing/roadmap.md b/docs/source/contributing/roadmap.md index 0a620cad..4148a7a7 100644 --- a/docs/source/contributing/roadmap.md +++ b/docs/source/contributing/roadmap.md @@ -7,6 +7,7 @@ The goal is to communicate priorities and upcoming release plans. It is not a aimed at limiting contributions to what is listed here. ## Using the roadmap + ### Sharing Feedback on the Roadmap All of the community is encouraged to provide feedback as well as share new @@ -16,24 +17,22 @@ After submitting the issue, others from the community will probably respond with questions or comments they have to clarify the issue. The maintainers will help identify what a good next step is for the issue. - ### What do we mean by "next step"? When submitting an issue, think about what "next step" category best describes your issue: -* **now**, concrete/actionable step that is ready for someone to start work on. -These might be items that have a link to an issue or more abstract like -"decrease typos and dead links in the documentation" -* **soon**, less concrete/actionable step that is going to happen soon, -discussions around the topic are coming close to an end at which point it can -move into the "now" category -* **later**, abstract ideas or tasks, need a lot of discussion or -experimentation to shape the idea so that it can be executed. Can also -contain concrete/actionable steps that have been postponed on purpose -(these are steps that could be in "now" but the decision was taken to work on -them later) - +- **now**, concrete/actionable step that is ready for someone to start work on. + These might be items that have a link to an issue or more abstract like + "decrease typos and dead links in the documentation" +- **soon**, less concrete/actionable step that is going to happen soon, + discussions around the topic are coming close to an end at which point it can + move into the "now" category +- **later**, abstract ideas or tasks, need a lot of discussion or + experimentation to shape the idea so that it can be executed. Can also + contain concrete/actionable steps that have been postponed on purpose + (these are steps that could be in "now" but the decision was taken to work on + them later) ### Reviewing and Updating the Roadmap @@ -48,22 +47,21 @@ For those please create a The roadmap should give the reader an idea of what is happening next, what needs input and discussion before it can happen and what has been postponed. - ## The roadmap proper + ### Project vision Repo2docker is a dependable tool used by humans that reduces the complexity of creating the environment in which a piece of software can be executed. - ### Now The "Now" items are being actively worked on by the project: -* reduce documentation typos and syntax errors -* increase test coverage to 80% (see https://codecov.io/gh/jupyterhub/repo2docker/tree/main/repo2docker for low coverage files) -* mounting repository contents in locations that is not `/home/jovyan` -* investigate options for pinning repo2docker versions ([#490](https://github.com/jupyterhub/repo2docker/issues/490)) +- reduce documentation typos and syntax errors +- increase test coverage to 80% (see https://codecov.io/gh/jupyterhub/repo2docker/tree/main/repo2docker for low coverage files) +- mounting repository contents in locations that is not `/home/jovyan` +- investigate options for pinning repo2docker versions ([#490](https://github.com/jupyterhub/repo2docker/issues/490)) ### Soon @@ -71,15 +69,16 @@ The "Soon" items are being discussed/a plan of action is being made. Once an item reaches the point of an actionable plan and person who wants to work on it, the item will be moved to the "Now" section. Typically, these will be moved at a future review of the roadmap. -* create the contributor highway, define the route from newcomer to project lead -* add Julia Manifest support (https://docs.julialang.org/en/v1/stdlib/Pkg/index.html, [#486](https://github.com/jupyterhub/repo2docker/issues/486)) -* support different base images/build pack stacks ([#487](https://github.com/jupyterhub/repo2docker/issues/487)) +- create the contributor highway, define the route from newcomer to project lead +- add Julia Manifest support (https://docs.julialang.org/en/v1/stdlib/Pkg/index.html, [#486](https://github.com/jupyterhub/repo2docker/issues/486)) +- support different base images/build pack stacks ([#487](https://github.com/jupyterhub/repo2docker/issues/487)) ### Later The "Later" items are things that are at the back of the project's mind. At this time there is no active plan for an item. The project would like to find the resources and time to discuss and then execute these ideas. -* support execution on a remote host (with more resources than available locally) via the command-line -* add support for using ZIP files as the repo (`repo2docker https://example.com/an-archive.zip`) + +- support execution on a remote host (with more resources than available locally) via the command-line +- add support for using ZIP files as the repo (`repo2docker https://example.com/an-archive.zip`) diff --git a/docs/source/contributing/tasks.md b/docs/source/contributing/tasks.md index 3fe47585..6deae1c0 100644 --- a/docs/source/contributing/tasks.md +++ b/docs/source/contributing/tasks.md @@ -32,17 +32,18 @@ py.test -s tests/ To skip the tests related to Mercurial repositories (to avoid to install Mercurial and hg-evolve), one can use the environment variable -``REPO2DOCKER_SKIP_HG_TESTS``. +`REPO2DOCKER_SKIP_HG_TESTS`. ### Troubleshooting Tests Some of the tests have non-python requirements for your development machine. They are: - `git-lfs` must be installed ([instructions](https://github.com/git-lfs/git-lfs)). It need not be activated -- there is no need to run the `git lfs install` command. It just needs to be available to the test suite. - - If your test failure messages include "`git-lfs filter-process: git-lfs: command not found`", this step should address the problem. + + - If your test failure messages include "`git-lfs filter-process: git-lfs: command not found`", this step should address the problem. - Minimum Docker Image size of 128GB is required. If you are not running docker on a linux OS, you may need to expand the runtime image size for your installation. See Docker's instructions for [macOS](https://docs.docker.com/docker-for-mac/space/) or [Windows 10](https://docs.docker.com/docker-for-windows/#resources) for more information. - - If your test failure messages include "`No space left on device: '/home/...`", this step should address the problem. + - If your test failure messages include "`No space left on device: '/home/...`", this step should address the problem. ## Update and Freeze BuildPack Dependencies @@ -51,35 +52,36 @@ dependencies that are installed by default for several buildpacks. For both the `conda` and `virtualenv` (`pip`) base environments in the **Conda BuildPack** and **Python BuildPack**, we install specific pinned versions of all dependencies. We explicitly list the dependencies -we want, then *freeze* them at commit time to explicitly list all the +we want, then _freeze_ them at commit time to explicitly list all the transitive dependencies at current versions. This way, we know that all dependencies will have the exact same version installed at all times. To update one of the dependencies shared across all `repo2docker` builds, you must follow these steps (with more detailed information in the sections below): -1. Bump the version numbers of the dependencies you want to update in the `conda` environment ([link](tasks:conda-dependencies)) +1. Bump the version numbers of the dependencies you want to update in the `conda` environment ([link](tasks:conda-dependencies)) 2. Make a pull request with your changes ([link](https://github.com/jupyterhub/repo2docker/blob/HEAD/CONTRIBUTING.md#make-a-pull-request)) See the subsections below for more detailed instructions. (tasks:conda-dependencies)= + ### Conda dependencies 1. There are two files related to conda dependencies. Edit as needed. - - `repo2docker/buildpacks/conda/environment.yml` + - `repo2docker/buildpacks/conda/environment.yml` - Contains list of packages to install in Python3 conda environments, - which are the default. **This is where all Notebook versions & - notebook extensions (such as JupyterLab / nteract) go**. + Contains list of packages to install in Python3 conda environments, + which are the default. **This is where all Notebook versions & + notebook extensions (such as JupyterLab / nteract) go**. - - `repo2docker/buildpacks/conda/environment.py-2.7.yml` + - `repo2docker/buildpacks/conda/environment.py-2.7.yml` - Contains list of packages to install in Python2 conda environments, which - can be specifically requested by users. **This only needs `IPyKernel` - and kernel related libraries**. Notebook / Notebook Extension need - not be installed here. + Contains list of packages to install in Python2 conda environments, which + can be specifically requested by users. **This only needs `IPyKernel` + and kernel related libraries**. Notebook / Notebook Extension need + not be installed here. 2. Once you edit either of these files to add a new package / bump version on an existing package, you should then run: @@ -147,14 +149,13 @@ Once this has completed, make sure that the new version has been updated. Once the new release has been pushed to PyPI, we need to create a new release on the [GitHub repository releases page](https://github.com/jupyterhub/repo2docker/releases). Once on that page, follow these steps: -* Click "Draft a new release" -* Choose a tag version using the same tag you just created above -* The release name is simply the tag version -* Finally, click "Publish release" +- Click "Draft a new release" +- Choose a tag version using the same tag you just created above +- The release name is simply the tag version +- Finally, click "Publish release" That's it! - # Uncommon tasks ## Compare generated Dockerfiles between repo2docker versions diff --git a/docs/source/design.md b/docs/source/design.md index e7083563..7f653694 100644 --- a/docs/source/design.md +++ b/docs/source/design.md @@ -7,8 +7,7 @@ The philosophy for the repo2docker buildpacks includes: - using common configuration files for familiar installation and packaging tools - allowing configuration files to be combined to compose more complex setups - specifying default locations for configuration files -(in the repository's root, `binder` or `.binder` directory) - + (in the repository's root, `binder` or `.binder` directory) When designing `repo2docker` and adding to it in the future, the developers are influenced by two primary use cases. @@ -79,7 +78,7 @@ is a highly recommended quick read. Although other projects, like [s2i](https://github.com/openshift/source-to-image), exist to convert source to Docker images, `repo2docker` provides the additional functionality to support -*composable* environments. We want to easily have an image with +_composable_ environments. We want to easily have an image with Python3+Julia+R-3.2 environments, rather than just one single language environment. While generally one language environment per container works well, in many scientific / datascience computing environments you need multiple diff --git a/tests/conda/README.md b/tests/conda/README.md index 15697619..6f137f61 100644 --- a/tests/conda/README.md +++ b/tests/conda/README.md @@ -57,7 +57,7 @@ `--target-repo-dir` is meant to support custom paths where repositories can be copied to besides `${HOME}`. - + This test makes use of the `test-extra-args.yaml` file to influence additional arguments passed to `repo2docker` during the test. In this test, specify `--target-repo-dir=/srv/repo`.