Merge pull request #615 from parente/doc-contributing

Some contributor documentation

.github/issue_template.md

-Hi! Thanks for using Jupyter's docker-stacks images.
+Hi! Thanks for using the Jupyter Docker Stacks.
 
-If you are requesting a library upgrade or addition in one of the existing images, please state the desired library name and version here and disregard the remaining sections.
+If you are looking to contribute to the images, please see the [Contributor's Guide] (http://jupyter-docker-stacks.readthedocs.io/en/latest/#) in the documentation for our preferred processes.
 
 If you are reporting an issue with one of the existing images, please answer the questions below to help us troubleshoot the problem. Please be as thorough as possible.
 

docs/contributing/features.md

+# New Features
+
+Thank you for contributing to 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.html#Core-Stacks), as a [recipe in the documentation](recipes.html), as a [community stack](stacks.html), 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?
+
+## 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:
+```
+make image/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.
+5. Discuss changes with the maintainers and address any build issues.

docs/contributing/packages.md

-# Packages
+# Package Updates
 
-## Package Updates
+We are actively seeking pull requests which update packages already included in the project Dockerfiles. This is a great way for first-time contributors to participate in developing docker-stacks.
 
-## New Packages
\ No newline at end of file
+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:
+```
+make image/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.

docs/contributing/recipes.md

-# Recipes
\ No newline at end of file
+# New Recipes
+
+We welcome contributions of [recipes](../using/recipes.html), short examples of using, configuring, or extending the Docker Stacks, for inclusion in the documentation site. Follow the process below to add a new recipe:
+
+1. Open the `docs/using/recipes.md` source file.
+2. Add a second-level Markdown heading naming your recipe at the bottom of the file (e.g., `## Add the RISE extension``)
+3. Write the body of your recipe under the heading, including whatever command line, Dockerfile, links, etc. you need.
+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. Discuss changes with the maintainers and address any formatting or content issues.

docs/index.rst

@@ -31,12 +31,14 @@ Table of Contents
    using/running
    using/common
    using/specifics
+   using/recipes
 
 .. toctree::
    :maxdepth: 2
    :caption: Contributor Guide
 
    contributing/packages
+   contributing/features
    contributing/recipes
    contributing/tests
    contributing/stacks

docs/using/running.md

@@ -9,7 +9,7 @@ This section provides details about the second.
 
 ## Using the Docker CLI
 
-You can launch a local Docker container from the Jupyter Docker Stacks using the [Docker command line interface](https://docs.docker.com/engine/reference/commandline/cli/). There are numerous ways to configure containers using the CLI. The following are a couple common patterns.
+You can launch a local Docker container from the Jupyter Docker Stacks using the [Docker command line interface](https://docs.docker.com/engine/reference/commandline/cli/). There are numerous ways to configure containers using the CLI. The following are some common patterns.
 
 **Example 1** This command pulls the `jupyter/scipy-notebook` image tagged `2c80cf3537ca` from Docker Hub if it is not already present on the local host. It then starts a container running a Jupyter Notebook server and exposes the server on host port 8888. The server logs appear in the terminal and include a URL to the notebook server.
 

docs/using/selecting.md

@@ -63,7 +63,7 @@ The Jupyter team maintains a set of Docker image definitions in the [https://git
 `jupyter/scipy-notebook` includes popular packages from the scientific Python ecosystem.
 
 * Everything in `jupyter/minimal-notebook` and its ancestor images
-* [pandas](https://pandas.pydata.org/), [numexpr](https://github.com/pydata/numexpr), [matplotlib](https://matplotlib.org/), [scipy](https://www.scipy.org/), [seaborn](https://seaborn.pydata.org/), [scikit-learn(http://scikit-learn.org/stable/)], [scikit-image](http://scikit-image.org/), [sympy](http://www.sympy.org/en/index.html), [cython](http://cython.org/), [patsy](https://patsy.readthedocs.io/en/latest/), [statsmodel](http://www.statsmodels.org/stable/index.html), [cloudpickle](https://github.com/cloudpipe/cloudpickle), [dill](https://pypi.python.org/pypi/dill), [numba](https://numba.pydata.org/), [bokeh](https://bokeh.pydata.org/en/latest/), [sqlalchemy](https://www.sqlalchemy.org/), [hdf5](http://www.h5py.org/), [vincent](http://vincent.readthedocs.io/en/latest/), [beautifulsoup](https://www.crummy.com/software/BeautifulSoup/), [protobuf](https://developers.google.com/protocol-buffers/docs/pythontutorial), and [xlrd](http://www.python-excel.org/) packages
+* [pandas](https://pandas.pydata.org/), [numexpr](https://github.com/pydata/numexpr), [matplotlib](https://matplotlib.org/), [scipy](https://www.scipy.org/), [seaborn](https://seaborn.pydata.org/), [scikit-learn](http://scikit-learn.org/stable/), [scikit-image](http://scikit-image.org/), [sympy](http://www.sympy.org/en/index.html), [cython](http://cython.org/), [patsy](https://patsy.readthedocs.io/en/latest/), [statsmodel](http://www.statsmodels.org/stable/index.html), [cloudpickle](https://github.com/cloudpipe/cloudpickle), [dill](https://pypi.python.org/pypi/dill), [numba](https://numba.pydata.org/), [bokeh](https://bokeh.pydata.org/en/latest/), [sqlalchemy](https://www.sqlalchemy.org/), [hdf5](http://www.h5py.org/), [vincent](http://vincent.readthedocs.io/en/latest/), [beautifulsoup](https://www.crummy.com/software/BeautifulSoup/), [protobuf](https://developers.google.com/protocol-buffers/docs/pythontutorial), and [xlrd](http://www.python-excel.org/) packages
 * [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) for interactive visualizations in Python notebooks
 * [Facets](https://github.com/PAIR-code/facets) for visualizing machine learning datasets