Document package updates, new feature contirbutions

docs/contributing/features.md

@@ -0,0 +1,24 @@
+# New Features
+
+We review contributions of new features (e.g., new packages, new scripts, new flags) to the project Dockerfiles in an attempt to balance the value of the images to the Jupyter community with the cost of maintaining the images over time. Roughly speaking, we think about the following when considering additions to the core stacks:
+
+* *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 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 scipts entirely?
+* *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?
+
+Follow the process below to suggest a new feature for inclusion in one of the core stacks:
+
+1. Open a GitHub issue describing the feature you'd like to contribute.
+2. Discuss 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.
+
+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. Try to build the image locally (`make image/somestack-notebook`) before submitting a pull request.
+    * Building the image locally gives you a shorter debugging cycle than waiting for [Travis CI](http://travis-ci.org/) to build your changes.
+    * Building locally also takes some load off of Travis CI which graciously provides free build services for open source projects like this one.
+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

@@ -1,5 +1,14 @@
-# Packages
+# Package Updates
 
-## Package Updates
+We welcome all contributions that update packages already included in the project Dockerfiles. Follow the process below to update a package version:
 
-## New Packages
+1. Locate the Dockerfile containing the library you wish to update.
+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. Try to build the image locally (`make image/somestack-notebook`) before submitting a pull request.
+    * Building the image locally gives you a shorter debugging cycle than waiting for [Travis CI](http://travis-ci.org/) to build your changes.
+    * Building locally also takes some load off of Travis CI which graciously provides free build services for open source projects like this one.
+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

@@ -1 +1 @@
-# Recipes
+# Documented Recipes

docs/index.rst

@@ -37,6 +37,7 @@ Table of Contents
    :caption: Contributor Guide
 
    contributing/packages
+   contributing/features
    contributing/recipes
    contributing/tests
    contributing/stacks