kopia lustrzana https://github.com/jupyterhub/repo2docker
[pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.cipull/1202/head
rodzic
94bd21e16e
commit
ae3aeb6dc5
|
@ -1,23 +1,27 @@
|
||||||
---
|
---
|
||||||
name: Bug report
|
name: Bug report
|
||||||
about: Create a report to help us repair something that is currently broken
|
about: Create a report to help us repair something that is currently broken
|
||||||
title: ''
|
title: ""
|
||||||
labels: ''
|
labels: ""
|
||||||
assignees: ''
|
assignees: ""
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<!-- Thank you for contributing. These HTML commments will not render in the issue, but you can delete them once you've read them if you prefer! -->
|
<!-- Thank you for contributing. These HTML commments will not render in the issue, but you can delete them once you've read them if you prefer! -->
|
||||||
|
|
||||||
### Bug description
|
### Bug description
|
||||||
|
|
||||||
<!-- Use this section to clearly and concisely describe the bug. -->
|
<!-- Use this section to clearly and concisely describe the bug. -->
|
||||||
|
|
||||||
#### Expected behaviour
|
#### Expected behaviour
|
||||||
|
|
||||||
<!-- Tell us what you thought would happen. -->
|
<!-- Tell us what you thought would happen. -->
|
||||||
|
|
||||||
#### Actual behaviour
|
#### Actual behaviour
|
||||||
|
|
||||||
<!-- Tell us what you actually happens. -->
|
<!-- Tell us what you actually happens. -->
|
||||||
|
|
||||||
### How to reproduce
|
### How to reproduce
|
||||||
|
|
||||||
<!-- Use this section to describe the steps that a user would take to experience this bug. -->
|
<!-- Use this section to describe the steps that a user would take to experience this bug. -->
|
||||||
|
|
||||||
1. Go to '...'
|
1. Go to '...'
|
||||||
|
@ -26,9 +30,9 @@ assignees: ''
|
||||||
4. See error
|
4. See error
|
||||||
|
|
||||||
### Your personal set up
|
### Your personal set up
|
||||||
|
|
||||||
<!-- Tell us a little about the system you're using. You can see the guidelines for setting up and reporting this information at https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#setting-up-for-local-development. -->
|
<!-- Tell us a little about the system you're using. You can see the guidelines for setting up and reporting this information at https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#setting-up-for-local-development. -->
|
||||||
|
|
||||||
- OS: [e.g. linux, OSX]
|
- OS: [e.g. linux, OSX]
|
||||||
- Docker version: `docker version` <!-- Run this command to get your version. -->
|
- Docker version: `docker version` <!-- Run this command to get your version. -->
|
||||||
- repo2docker version `repo2docker --version` <!-- Run this command to get your version. -->
|
- repo2docker version `repo2docker --version` <!-- Run this command to get your version. -->
|
||||||
|
|
||||||
|
|
|
@ -1,29 +1,29 @@
|
||||||
---
|
---
|
||||||
name: Feature request
|
name: Feature request
|
||||||
about: Suggest a new feature or a big change to repo2docker
|
about: Suggest a new feature or a big change to repo2docker
|
||||||
title: ''
|
title: ""
|
||||||
labels: 'needs: discussion'
|
labels: "needs: discussion"
|
||||||
assignees: ''
|
assignees: ""
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<!-- Thank you for contributing. These HTML commments will not render in the issue, but you can delete them once you've read them if you prefer! -->
|
<!-- Thank you for contributing. These HTML commments will not render in the issue, but you can delete them once you've read them if you prefer! -->
|
||||||
|
|
||||||
### Proposed change
|
### Proposed change
|
||||||
|
|
||||||
<!-- Use this section to describe the feature you'd like to be added. -->
|
<!-- Use this section to describe the feature you'd like to be added. -->
|
||||||
|
|
||||||
|
|
||||||
### Alternative options
|
### Alternative options
|
||||||
|
|
||||||
<!-- Use this section to describe alternative options and why you've decided on the proposed feature above. -->
|
<!-- Use this section to describe alternative options and why you've decided on the proposed feature above. -->
|
||||||
|
|
||||||
|
|
||||||
### Who would use this feature?
|
### Who would use this feature?
|
||||||
|
|
||||||
<!-- Describe the audience for this feature. This information will affect who chooses to work on the feature with you. -->
|
<!-- Describe the audience for this feature. This information will affect who chooses to work on the feature with you. -->
|
||||||
|
|
||||||
|
|
||||||
### How much effort will adding it take?
|
### How much effort will adding it take?
|
||||||
|
|
||||||
<!-- Try to estimate how much work adding this feature will require. This information will affect who chooses to work on the feature with you. -->
|
<!-- Try to estimate how much work adding this feature will require. This information will affect who chooses to work on the feature with you. -->
|
||||||
|
|
||||||
|
|
||||||
### Who can do this work?
|
### Who can do this work?
|
||||||
<!-- What skills are needed? Who can be recruited to add this feature? This information will affect who chooses to work on the feature with you. -->
|
|
||||||
|
|
||||||
|
<!-- What skills are needed? Who can be recruited to add this feature? This information will affect who chooses to work on the feature with you. -->
|
||||||
|
|
|
@ -1,10 +1,9 @@
|
||||||
---
|
---
|
||||||
name: Support question
|
name: Support question
|
||||||
about: Ask a question about using repo2docker
|
about: Ask a question about using repo2docker
|
||||||
title: ''
|
title: ""
|
||||||
labels: ''
|
labels: ""
|
||||||
assignees: ''
|
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. 🚨
|
🚨 Please do **not** open an issue for support questions. Instead please search for similar issues or post on http://discourse.jupyter.org/c/questions. 🚨
|
||||||
|
|
|
@ -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.
|
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:
|
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.
|
- [Process for making a contribution](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#process-for-making-a-contribution).
|
||||||
* [Guidelines to getting a Pull Request merged](https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#guidelines-to-getting-a-pull-request-merged).
|
- These steps talk you through choosing the right issue template (bug report or feature request) and making a change.
|
||||||
* These are tips and tricks to help make your contribution as smooth as possible for you and for the repo2docker maintenance team.
|
- [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:
|
There are a few other pages to highlight:
|
||||||
|
|
||||||
* [Our roadmap](https://repo2docker.readthedocs.io/en/latest/contributing/roadmap.html)
|
- [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.
|
- 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.
|
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)
|
- [Design of repo2docker](https://repo2docker.readthedocs.io/en/latest/design.html)
|
||||||
* This page explains some of the design principles behind repo2docker.
|
- 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!
|
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.
|
- 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)
|
- [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.
|
- Some notes on running tests, buildpack dependencies, creating a release, and keeping the pip files up to date.
|
||||||
|
|
|
@ -31,6 +31,7 @@ For more information, please visit
|
||||||
---
|
---
|
||||||
|
|
||||||
## Using repo2docker
|
## Using repo2docker
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
|
||||||
1. Docker to build & run the repositories. The [community edition](https://store.docker.com/search?type=edition&offering=community)
|
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
|
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!
|
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).
|
[usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html).
|
||||||
|
|
||||||
|
|
||||||
## Repository specifications
|
## Repository specifications
|
||||||
|
|
||||||
Repo2Docker looks for configuration files in the source repository to
|
Repo2Docker looks for configuration files in the source repository to
|
||||||
determine how the Docker image should be built. For a list of the configuration
|
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).
|
[complete list of configuration files](https://repo2docker.readthedocs.io/en/latest/config_files.html).
|
||||||
|
|
||||||
The philosophy of repo2docker is inspired by
|
The philosophy of repo2docker is inspired by
|
||||||
[Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks).
|
[Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks).
|
||||||
|
|
||||||
|
|
||||||
## Docker Image
|
## 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.
|
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.
|
||||||
|
|
|
@ -4,6 +4,7 @@ This is a living document talking about the architecture of repo2docker
|
||||||
from various perspectives.
|
from various perspectives.
|
||||||
|
|
||||||
(buildpacks)=
|
(buildpacks)=
|
||||||
|
|
||||||
## Buildpacks
|
## Buildpacks
|
||||||
|
|
||||||
The **buildpack** concept comes from [Heroku](https://devcenter.heroku.com/articles/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
|
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
|
[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`,
|
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).
|
already been built and cached).
|
||||||
|
|
||||||
The `get_build_scripts` and `get_build_script_files` methods are primarily used for this.
|
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
|
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:
|
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,
|
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
|
since there's no `requirements.txt` inside the image at this point. This is an explicit
|
||||||
design decision, to enable better layer caching.
|
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`,
|
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
|
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.
|
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
|
`repo2docker` will loop through all ContentProviders and perform the following
|
||||||
commands:
|
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
|
should return any value other than `None` if the path matches what the ContentProvider is looking
|
||||||
for.
|
for.
|
||||||
|
|
||||||
|
@ -126,12 +127,11 @@ commands:
|
||||||
> checks whether the argument is a valid local path. If so, then `detect(`
|
> 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.
|
> 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.
|
> 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
|
returned value as its argument. This should
|
||||||
result in the contents of the repository being placed locally to a folder.
|
result in the contents of the repository being placed locally to a folder.
|
||||||
|
|
||||||
For more information on ContentProviders, take a look at
|
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)
|
[the ContentProvider base class](https://github.com/jupyterhub/repo2docker/blob/80b979f8580ddef184d2ba7d354e7a833cfa38a4/repo2docker/contentproviders/base.py#L16-L60)
|
||||||
which has more explanation.
|
which has more explanation.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -2,33 +2,33 @@
|
||||||
|
|
||||||
Thank you for thinking about contributing to repo2docker!
|
Thank you for thinking about contributing to repo2docker!
|
||||||
This is an open source project that is developed and maintained entirely by volunteers.
|
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!
|
THANK YOU!
|
||||||
|
|
||||||
## Types of contribution
|
## Types of contribution
|
||||||
|
|
||||||
There are many ways to contribute to repo2docker:
|
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.
|
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.
|
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).
|
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!
|
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).
|
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.
|
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!
|
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).
|
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.
|
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
|
Whenever somebody proposes changes to the repo2docker codebase, the community reviews
|
||||||
the changes, and provides feedback, edits, and suggestions. Check out the
|
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)
|
[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
|
and provide feedback that helps improve the PR and get it merged. Please keep your
|
||||||
feedback positive and constructive!
|
feedback positive and constructive!
|
||||||
* **Tell people about repo2docker.**
|
- **Tell people about repo2docker.**
|
||||||
As we said above, repo2docker is built by and for its community.
|
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!
|
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.
|
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).
|
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.
|
**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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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).
|
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).
|
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.
|
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.
|
5. Wait for a community member to merge your changes.
|
||||||
Remember that **someone else must merge your pull request**.
|
Remember that **someone else must merge your pull request**.
|
||||||
That goes for new contributors and long term maintainers alike.
|
That goes for new contributors and long term maintainers alike.
|
||||||
Because `main` is continuously deployed to mybinder.org it is essential
|
Because `main` is continuously deployed to mybinder.org it is essential
|
||||||
that `main` is always in a deployable state.
|
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)
|
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)=
|
(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.
|
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.
|
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.
|
The best PRs solve one problem.
|
||||||
If you end up changing multiple things, please open separate PRs for the different conceptual changes.
|
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.
|
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.
|
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" <deployed-revision>..` and your PR easier to review.
|
This makes it easier to find all changes since the last deployment `git log --merges --pretty=format:"%h %<(10,trunc)%an %<(15)%ar %s" <deployed-revision>..` 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.
|
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.**
|
- **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).
|
- **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.
|
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.
|
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.)
|
(Remember that **someone else** must merge your PR, even if you have the admin rights to do so.)
|
||||||
|
|
||||||
(contributing:local-dev)=
|
(contributing:local-dev)=
|
||||||
|
|
||||||
## Setting up for Local Development
|
## Setting up for Local Development
|
||||||
|
|
||||||
To develop & test repo2docker locally, you need:
|
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
|
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.
|
formatted properly and the tests will fail if this is not the case.
|
||||||
|
|
||||||
|
|
||||||
### Verify that docker is installed and running
|
### Verify that docker is installed and running
|
||||||
|
|
||||||
If you do not already have [Docker](https://www.docker.com/), you should be able
|
If you do not already have [Docker](https://www.docker.com/), you should be able
|
||||||
|
|
|
@ -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.
|
It is not a aimed at limiting contributions to what is listed here.
|
||||||
|
|
||||||
## Using the roadmap
|
## Using the roadmap
|
||||||
|
|
||||||
### Sharing Feedback on the Roadmap
|
### Sharing Feedback on the Roadmap
|
||||||
|
|
||||||
All of the community is encouraged to provide feedback as well as share new
|
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
|
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.
|
maintainers will help identify what a good next step is for the issue.
|
||||||
|
|
||||||
|
|
||||||
### What do we mean by "next step"?
|
### What do we mean by "next step"?
|
||||||
|
|
||||||
When submitting an issue, think about what "next step" category best describes
|
When submitting an issue, think about what "next step" category best describes
|
||||||
your issue:
|
your issue:
|
||||||
|
|
||||||
* **now**, concrete/actionable step that is ready for someone to start work on.
|
- **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
|
These might be items that have a link to an issue or more abstract like
|
||||||
"decrease typos and dead links in the documentation"
|
"decrease typos and dead links in the documentation"
|
||||||
* **soon**, less concrete/actionable step that is going to happen soon,
|
- **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
|
discussions around the topic are coming close to an end at which point it can
|
||||||
move into the "now" category
|
move into the "now" category
|
||||||
* **later**, abstract ideas or tasks, need a lot of discussion or
|
- **later**, abstract ideas or tasks, need a lot of discussion or
|
||||||
experimentation to shape the idea so that it can be executed. Can also
|
experimentation to shape the idea so that it can be executed. Can also
|
||||||
contain concrete/actionable steps that have been postponed on purpose
|
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
|
(these are steps that could be in "now" but the decision was taken to work on
|
||||||
them later)
|
them later)
|
||||||
|
|
||||||
|
|
||||||
### Reviewing and Updating the Roadmap
|
### 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
|
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.
|
input and discussion before it can happen and what has been postponed.
|
||||||
|
|
||||||
|
|
||||||
## The roadmap proper
|
## The roadmap proper
|
||||||
|
|
||||||
### Project vision
|
### Project vision
|
||||||
|
|
||||||
Repo2docker is a dependable tool used by humans that reduces the complexity of
|
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.
|
creating the environment in which a piece of software can be executed.
|
||||||
|
|
||||||
|
|
||||||
### Now
|
### Now
|
||||||
|
|
||||||
The "Now" items are being actively worked on by the project:
|
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
|
### 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
|
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
|
it, the item will be moved to the "Now" section. Typically, these will be moved
|
||||||
at a future review of the roadmap.
|
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
|
### Later
|
||||||
|
|
||||||
The "Later" items are things that are at the back of the project's mind. At this
|
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
|
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.
|
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`)
|
||||||
|
|
|
@ -32,17 +32,18 @@ py.test -s tests/<path-to-test>
|
||||||
|
|
||||||
To skip the tests related to Mercurial repositories (to avoid to install
|
To skip the tests related to Mercurial repositories (to avoid to install
|
||||||
Mercurial and hg-evolve), one can use the environment variable
|
Mercurial and hg-evolve), one can use the environment variable
|
||||||
``REPO2DOCKER_SKIP_HG_TESTS``.
|
`REPO2DOCKER_SKIP_HG_TESTS`.
|
||||||
|
|
||||||
### Troubleshooting Tests
|
### Troubleshooting Tests
|
||||||
|
|
||||||
Some of the tests have non-python requirements for your development machine. They are:
|
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.
|
- `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.
|
- 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
|
## 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**,
|
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 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
|
transitive dependencies at current versions. This way, we know that
|
||||||
all dependencies will have the exact same version installed at all times.
|
all dependencies will have the exact same version installed at all times.
|
||||||
|
|
||||||
To update one of the dependencies shared across all `repo2docker` builds, you
|
To update one of the dependencies shared across all `repo2docker` builds, you
|
||||||
must follow these steps (with more detailed information in the sections below):
|
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))
|
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.
|
See the subsections below for more detailed instructions.
|
||||||
|
|
||||||
(tasks:conda-dependencies)=
|
(tasks:conda-dependencies)=
|
||||||
|
|
||||||
### Conda dependencies
|
### Conda dependencies
|
||||||
|
|
||||||
1. There are two files related to conda dependencies. Edit as needed.
|
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,
|
Contains list of packages to install in Python3 conda environments,
|
||||||
which are the default. **This is where all Notebook versions &
|
which are the default. **This is where all Notebook versions &
|
||||||
notebook extensions (such as JupyterLab / nteract) go**.
|
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
|
Contains list of packages to install in Python2 conda environments, which
|
||||||
can be specifically requested by users. **This only needs `IPyKernel`
|
can be specifically requested by users. **This only needs `IPyKernel`
|
||||||
and kernel related libraries**. Notebook / Notebook Extension need
|
and kernel related libraries**. Notebook / Notebook Extension need
|
||||||
not be installed here.
|
not be installed here.
|
||||||
|
|
||||||
2. Once you edit either of these files to add a new package / bump version on
|
2. Once you edit either of these files to add a new package / bump version on
|
||||||
an existing package, you should then run:
|
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
|
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:
|
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"
|
- Click "Draft a new release"
|
||||||
* Choose a tag version using the same tag you just created above
|
- Choose a tag version using the same tag you just created above
|
||||||
* The release name is simply the tag version
|
- The release name is simply the tag version
|
||||||
* Finally, click "Publish release"
|
- Finally, click "Publish release"
|
||||||
|
|
||||||
That's it!
|
That's it!
|
||||||
|
|
||||||
|
|
||||||
# Uncommon tasks
|
# Uncommon tasks
|
||||||
|
|
||||||
## Compare generated Dockerfiles between repo2docker versions
|
## Compare generated Dockerfiles between repo2docker versions
|
||||||
|
|
|
@ -7,8 +7,7 @@ The philosophy for the repo2docker buildpacks includes:
|
||||||
- using common configuration files for familiar installation and packaging tools
|
- using common configuration files for familiar installation and packaging tools
|
||||||
- allowing configuration files to be combined to compose more complex setups
|
- allowing configuration files to be combined to compose more complex setups
|
||||||
- specifying default locations for configuration files
|
- 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
|
When designing `repo2docker` and adding to it in the future, the
|
||||||
developers are influenced by two primary use cases.
|
developers are influenced by two primary use cases.
|
||||||
|
@ -79,7 +78,7 @@ is a highly recommended quick read.
|
||||||
Although other projects, like
|
Although other projects, like
|
||||||
[s2i](https://github.com/openshift/source-to-image), exist to convert source to
|
[s2i](https://github.com/openshift/source-to-image), exist to convert source to
|
||||||
Docker images, `repo2docker` provides the additional functionality to support
|
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
|
Python3+Julia+R-3.2 environments, rather than just one single language
|
||||||
environment. While generally one language environment per container works well,
|
environment. While generally one language environment per container works well,
|
||||||
in many scientific / datascience computing environments you need multiple
|
in many scientific / datascience computing environments you need multiple
|
||||||
|
|
|
@ -57,7 +57,7 @@
|
||||||
|
|
||||||
`--target-repo-dir` is meant to support custom paths where repositories can be
|
`--target-repo-dir` is meant to support custom paths where repositories can be
|
||||||
copied to besides `${HOME}`.
|
copied to besides `${HOME}`.
|
||||||
|
|
||||||
This test makes use of the `test-extra-args.yaml` file to influence additional
|
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
|
arguments passed to `repo2docker` during the test. In this test, specify
|
||||||
`--target-repo-dir=/srv/repo`.
|
`--target-repo-dir=/srv/repo`.
|
||||||
|
|
Ładowanie…
Reference in New Issue