Clarity (#38)

* Initial commit of compatibility notices page; added to index

* Replace references to Anaconda with Miniconda

* Add pipeline release description

* We no longer keep things like new. We update them.

* Use more targeted wording

* Replace or enhance references to anaconda with miniconda, or just conda depending on context

* Reword/improve config section

8 files changed, 76 insertions, 31 deletions

diff --git a/source/compat.rst b/source/compat.rst
new file mode 100644
index 0000000..287f91e
--- /dev/null
+++ b/source/compat.rst
@@ -0,0 +1,30 @@
+*********************
+Compatibility Notices
+*********************
+
+As the Conda package ecosystem evolves and third-party software updates are released by Continuum and other providers, this may interfere with the stability of other codebases, such as STScI's software. This page will proactively chronicle such events as they occur as well as provide workarounds to these issues.
+
+If you spot a compatibility problem not listed here please let us know by sending an email to help@stsci.edu
+
+.. note::
+
+  **You may be effected by an issue if you have updated your AstroConda environment on or after the dates listed in each section below.**
+
+
+12/23/2016
+==========
+
+AstroPy v1.3 fully deprecated calls to ``astropy.io.fits.new_table``. The following packages are known to be incompatiable with this release:
+
+  * ``calcos =< 3.1.8`` - Bugfix pending
+  * ``costools <= 1.2.1`` - Bugfix pending
+  * ``fitsblender =< 0.2.6`` - 0.3.0 released (01/17/2017)
+
+Recommended user actions:
+
+  * Upgrade ``fitsblender`` to version 0.3.0 (i.e. ``conda update fitsblender``)
+
+Alternative user actions:
+
+  * Downgrade ``astropy`` to version 1.2.1 (i.e. ``conda install astropy=1.2.1``)
+
diff --git a/source/contributing.rst b/source/contributing.rst
index 4e861c3..e0930c0 100644
--- a/source/contributing.rst
+++ b/source/contributing.rst
@@ -71,7 +71,7 @@ If you have taken the liberty of looking around the astroconda-contrib directory
 
 .. note::
 
-    This is not an Anaconda packaging tutorial. For more information about creating recipes from scratch, please refer to the `conda-build documentation <http://conda.pydata.org/docs/build_tutorials/pkgs2.html>`_.
+    This is not an full Conda packaging tutorial. For more information about creating recipes from scratch, please refer to the `conda-build documentation <http://conda.pydata.org/docs/build_tutorials/pkgs2.html>`_.
 
     **Hint:** Investigate the contents of the recipes in astroconda-contrib. For most cases, copying an existing recipe and changing its values will suffice.
 
@@ -271,7 +271,7 @@ Python 3.5:
 
 That's probably a bit more involved than you thought. Let's break it down. We issue ``-c [URL]`` which instructs the build to utilize the AstroConda channel while checking for package dependencies (i.e. the recipe's ``requirements`` section). Secondly, we issue ``--skip-existing`` to prevent ``conda build`` from rebuilding dependencies discovered in the local astroconda-contrib directory. That is to say, if a package defined as a requirement exists remotely, it will then download and install it, rather than rebuild it from scratch. ``--python=`` is self-explanatory, and the final argument is the name of the recipe(s) we intend to build.
 
-At this point, if the build was successful, our Conda package (a bzipped tarball) called ``sympy-1.0-py35_0.tar.bz2`` is emitted to ``/path/to/anaconda/conda-bld/[os-arch]/``. This directory is a local Conda package repository.
+At this point, if the build was successful, our Conda package (a bzipped tarball) called ``sympy-1.0-py35_0.tar.bz2`` is emitted to ``/path/to/miniconda3/conda-bld/[os-arch]/``. This directory is a local Conda package repository.
 
 To install this new ``sympy`` package and interact with it ourselves you could run the following:
 
@@ -292,7 +292,7 @@ And checking it out for yourself:
 
     >>> import sympy
     >>> sympy.__file__
-    '/path/to/anaconda/envs/sympy_test/lib/python3.5/site-packages/sympy/__init__.py'
+    '/path/to/miniconda3/envs/sympy_test/lib/python3.5/site-packages/sympy/__init__.py'
 
 Now that you have verified the recipe is fully functional and are happy with the outcome, it's time to create a pull request against astroconda-contrib main repository.
 
diff --git a/source/faq.rst b/source/faq.rst
index 852890a..2f2faf4 100644
--- a/source/faq.rst
+++ b/source/faq.rst
@@ -48,24 +48,23 @@ We recommend against using the astroconda.org mirror on a regular basis. The ban
 After "conda create -n ..." why does "source activate astroconda" fail?
 ============================================================================
 
-Anaconda does not support CSH (C-Shell). Please switch to a POSIX-compatible shell (e.g. BASH, KSH, ZSH).
+Conda does not support CSH (C-Shell). Please switch to a POSIX-compatible shell (e.g. BASH, KSH, ZSH).
 
 .. note::
 
-    STScI will not maintain a separate codebase of Anaconda's backend ``conda`` in order to implement CSH support. Feel free to create an issue with the `developers <http://github.com/conda/conda/issues>`_.
+    STScI will not maintain a separate codebase of ``conda`` in order to implement CSH support. Feel free to create an issue with the `developers <http://github.com/conda/conda/issues>`_.
 
-I installed AstroConda into my Anaconda 'root' environment. What now?
-=====================================================================
+I installed AstroConda into my [Mini/Ana]conda 'root' environment. What now?
+============================================================================
 
-Please reinstall Anaconda from scratch. AstroConda uses ``source activate`` and ``source deactivate`` calls to
-control your shell environment. The Anaconda 'root' environment **does not** use this feature, and thus, the packages you have installed there will not work properly.
+Please reinstall Miniconda (or Anaconda) from scratch. AstroConda uses ``source activate`` and ``source deactivate`` calls to control your shell environment. The Anaconda 'root' environment **does not** use this feature, and thus, the packages you have installed there will not work properly.
 
-To clarify, it is impossible to execute ``source activate root``. Installing AstroConda packages directly into the 'root' may cause Anaconda itself to be come unstable. In addition to this, removing packages from this environment is tedious and will likely break your Anaconda installation if you are not careful. *Reinstalling from scratch is the safest option.*
+To clarify, installing AstroConda packages directly into the 'root' may cause Miniconda (or Anaconda) itself to be come unstable. In addition to this, removing packages from this environment is tedious and will likely break your Anaconda installation if you are not careful. *Reinstalling from scratch is the safest option.*
 
 Why am I being prompted by NumPy/SciPy with a MKL 30-day trial warning?
 =======================================================================
 
-The ``root`` environment of your Anaconda installation is severely outdated (``<=2.4.0``) and suffers from a crippling bug introduced by the ``conda-3.19.x`` package.
+The ``root`` environment of your installation is severely outdated (``<=2.4.0``) and suffers from a crippling bug introduced by the ``conda-3.19.x`` package.
 
 It is possible to verify the version of Anaconda you have by running:
 
@@ -167,7 +166,7 @@ RHEL/CentOS >=6, Fedora >=14
 Will AstroConda interfere with other scientific distributions (e.g. SciSoft)?
 =============================================================================
 
-**Probably**, however unlike Ureka, we do not impose any restrictions on your environment or issue compatibility warnings at run-time. It is your responsibility to maintain a functional shell environment so [insert scientific distribution here] does not conflict with your Anaconda installation.
+**Probably**, however unlike Ureka, we do not impose any restrictions on your environment or issue compatibility warnings at run-time. It is your responsibility to maintain a functional shell environment so [insert scientific distribution here] does not conflict with your Conda installation.
 
 Ds9 - Cannot select regions
 ===========================
diff --git a/source/index.rst b/source/index.rst
index de131e6..52bc8da 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -14,6 +14,7 @@ To receive AstroConda announcements, or to engage in general discussion, feel fr
    installation
    releases
    updating
+   compat
    faq
    contributing
    package_manifest
diff --git a/source/installation.rst b/source/installation.rst
index 871d917..45b4d23 100644
--- a/source/installation.rst
+++ b/source/installation.rst
@@ -4,41 +4,48 @@ Installation
 
 Before you begin, the list below contains known requirements and limitations of AstroConda:
 
-    - This documentation targets Anaconda3 (i.e. Python 3), but the installation instructions work equally well with any of the Anaconda distributions.
+    - This documentation targets Miniconda3 (i.e. Python 3), but the installation instructions work equally well with any of the Miniconda distributions.
     - AstroConda supports Linux (glibc ≥ 2.12) and Mac OS X (≥ 10.7; 10.6 is NOT supported)
     - AstroConda contains packages for 64-bit [#archnote]_ Python 2.7 and 3.5.
     - Conda only supports BASH and ZSH environments. If you are a native CSH user, execute ``bash -l`` prior to performing the procedures detailed in this guide.
-    - IRAF users: After configuring Anaconda for use with AstroConda, refer to the :ref:`iraf_install` section of this guide to continue your installation.
+    - IRAF users: After configuring Miniconda for use with AstroConda, refer to the :ref:`iraf_install` section of this guide to continue your installation.
 
-Obtain Anaconda
-===============
+Obtain Miniconda
+================
 
 .. note::
 
-    Installing Anaconda3 will not prevent you from using Python 2.
-
-    ``conda`` allows you to deploy multiple independent Python environments, at-will, under a single Anaconda installation. You may have trouble following along with this guide if you choose to install Anaconda2.
+    Installing Miniconda3 will not prevent you from using Python 2.
 
+    ``conda`` allows you to deploy multiple independent Python environments, at-will, under a single Miniconda installation. You may have trouble following along with this guide if you choose to install Miniconda2.
 
-Go grab a copy of `Anaconda3 <https://www.continuum.io/downloads>`_ from Continuum Analytics, Inc. Be sure to select the installation medium appropriate for your operating system (Linux or OS X) and architecture (64-bit). The OS X GUI installer may cause side-effects, such as changing permissions of files in your home directory to ``root:wheel``, or mistakenly creating a system-wide installation under ``/anaconda`` instead of your personal home directory. To avoid this situation perform a command-line installation instead.
 
-Follow the installation instructions for your platform provided on the download page. Before moving on to the next step, open a new terminal window, and run ``conda`` to verify your terminal session can find it.
+Go grab a copy of `Miniconda3 <http://conda.pydata.org/miniconda.html>`_ from Continuum Analytics, Inc. Be sure to select the installation medium appropriate for your operating system (Linux or OS X) and architecture (64-bit). Follow the installation instructions for your platform provided on the download page. Before moving on to the next step, open a new terminal window, and run ``conda`` to verify your terminal session can find it.
 
 
 Configure Conda
 ===============
 
-In order to install packages directly from the AstroConda repository, you will need to configure Anaconda to do so. This will permanently add the repository to Conda's search path. Be aware that adding additional `anaconda.org <https://anaconda.org>`_ or direct-url repositories may affect the stability of AstroConda's run-time environment.
+In order to install packages directly from the AstroConda repository, you will need to configure Conda to do so.
 
 .. code-block:: sh
 
     $ conda config --add channels http://ssb.stsci.edu/astroconda
     # Writes changes to ~/.condarc
 
+This command will append the AstroConda channel URL to Conda's channel search path. Be aware that adding additional `anaconda.org <https://anaconda.org>`_ or direct-url repositories can potentially effect thestability of AstroConda's run-time environment.
+
+For example, if you add a channel found on anaconda.org because it contains a software package you're interested in, but also provides the same software as AstroConda, it's possible you may lose track of where packages are coming from. If you decide to have multiple channels defined in your configuration and bugs begin to appear, it may be best to check their origin before issuing a support ticket to help@stsci.edu. ``conda list`` can be used to display such information about the packages installed in your environment.
+
 
 Install AstroConda
 ==================
 
+.. caution::
+
+    If you wish to install a copy of a mission-specific operational data processing environment, please `click here <releases.html>`_.
+
+
 Standard Installation (without IRAF)
 ------------------------------------
 
@@ -91,6 +98,7 @@ Then, just as with the default installation, it is necessary to activate the env
 
     $ source activate iraf27
 
+
 Fine-tuning the Installation
 ============================
 
@@ -108,14 +116,14 @@ AstroConda provides a suite of packages that are known to work well together and
 
 Full documentation of the ``conda`` tool is available from Continuum Analytics, Inc., its creators and maintainers: http://conda.pydata.org/docs/using/index.html. However, we have provided a brief explanation of 3rd-party package installation below for quick reference.
 
-For scientific packages available through Anaconda, installation is as simple as:
+For scientific packages available through Miniconda, installation is as simple as:
 
 .. code-block:: sh
 
     $ source activate astroconda
     $ conda install name_of_pkg
 
-Often, the easiest way to see if the package is available through Anaconda is to try installing it. The full list of available packages is here: http://repo.continuum.io/pkgs/.
+Often, the easiest way to see if the package is available through Miniconda is to try installing it. The full list of available packages is here: http://repo.continuum.io/pkgs/.
 
 The Python-standard tool ``pip`` is also available to install packages distributed through the Python Package Index (PyPI):
 
diff --git a/source/releases.rst b/source/releases.rst
index 3cd552c..2c71c13 100644
--- a/source/releases.rst
+++ b/source/releases.rst
@@ -3,14 +3,17 @@ Pipeline Releases
 
 .. note::
 
-    - Python 2.x.x is not supported.
+    - Python 2.x.x is not supported (unless noted otherwise).
     - 32-bit operating systems are not supported.
 
+Pipeline releases differ from the standard AstroConda distribution and serve a different purpose. The release files described below are immutable snapshots of STScI operational software, and can be used to replicate the environment used by STScI to perform mission-specific data processing. Be aware that upgrading packages with ``conda update [pkg]`` is not recommended as it will likely introduce unwanted bugs and/or break the environment all together.
+
+If you have any questions, comments, or concerns related to pipeline releases please feel free to contact help@stsci.edu
 
 Installation
 ============
 
-To install a STScI pipeline release, use the following format:
+Pipeline release installations use the following ``conda create`` command format:
 
 .. code-block:: sh
 
diff --git a/source/resources.rst b/source/resources.rst
index 8c37baf..72aa243 100644
--- a/source/resources.rst
+++ b/source/resources.rst
@@ -49,13 +49,17 @@ Gemini Observatory
 - http://www.gemini.edu/node/10795
 
 
-Anaconda (Continuum Analytics, Inc.)
-====================================
+Miniconda & Anaconda (Continuum Analytics, Inc.)
+================================================
 
 .. important::
 
     AstroConda is not affiliated with Continuum Analytics, Inc. or its partners.
 
+**Miniconda**
+
+- http://conda.pydata.org/miniconda.html
+
 **Anaconda**
 
 - https://www.continuum.io/why-anaconda
diff --git a/source/updating.rst b/source/updating.rst
index 26bba18..f69d7d5 100644
--- a/source/updating.rst
+++ b/source/updating.rst
@@ -1,6 +1,6 @@
-*****************************
-Keeping AstroConda "Like New"
-*****************************
+********
+Updating
+********
 
 Anaconda's package manager, Conda, will not automatically update unless a newer version of a package is detected during a routine package installation. Suffice to say, unless you keep your packages up to date with ``conda update``, the packages installed in your Anaconda distribution will remain relatively static.