Instruct people to use a specific version (#14)

Our instructions said to clone the master branch. This is bad because we
can break everyone's builds by updating these scripts. Better to make
releases using semantic versioning and let users upgrade when they want.

.appveyor.yml

@@ -27,8 +27,8 @@ init:
     - "set PATH=%MINICONDA%;%MINICONDA%\\Scripts;%MINICONDA%\\Library\\bin;%PATH%"
 
 install:
-    # Get the Fatiando CI scripts
-    - cmd: git clone https://github.com/fatiando/continuous-integration.git
+    # Get the Fatiando CI scripts (replace "master" with the version you want to use)
+    - cmd: git clone --branch=master --depth=1 https://github.com/fatiando/continuous-integration.git
     # Setup miniconda and install the requirements into a new environment
     #- cmd: continuous-integration\appveyor\setup-miniconda.bat
     # We'll use the current script in this repo but you should use the above line

.travis.yml

@@ -64,12 +64,12 @@ matrix:
 
 # Setup the build environment
 before_install:
-    # Get the Fatiando CI scripts
-    - git clone https://github.com/fatiando/continuous-integration.git
+    # Get the Fatiando CI scripts (replace "master" with the version you want to use)
+    - git clone --branch=master --depth=1 https://github.com/fatiando/continuous-integration.git
     # Download and install miniconda and setup dependencies
     # Need to source the script to set the PATH variable globaly
     #- source continuous-integration/travis/setup-miniconda.sh
-    # We'll use the local version but you should use the line above
+    # We'll use the local version but you should use the line above instead
     - source travis/setup-miniconda.sh
     # Show installed pkg information for postmortem diagnostic
     - conda list

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Leonardo Uieda
+Copyright (c) 2018-2019 Leonardo Uieda
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,27 +1,43 @@
 # Scripts for managing Continuous Integration services
 
-Automate the process of installing miniconda and deploying to PyPI and Github Pages.
+Automate the process of installing miniconda, setting up a build environment, and
+deploying to PyPI and Github Pages from Continuous Integration (CI) services.
 
+[![AppVeyor build status](http://img.shields.io/appveyor/ci/fatiando/continuous-integration/master.svg?style=flat-square&label=AppVeyor)](https://ci.appveyor.com/project/fatiando/continuous-integration)
+[![TravisCI build status](http://img.shields.io/travis/fatiando/continuous-integration/master.svg?style=flat-square&label=TravisCI)](https://travis-ci.org/fatiando/continuous-integration)
+[![Latest release](https://img.shields.io/github/release/fatiando/continuous-integration.svg?style=flat-square)](https://github.com/fatiando/continuous-integration/releases/latest)
 
-## AppVeyor
+## Contents
 
-AppVeyor can be used to test the build on Windows (both 32 and 64bit). A very nice
-convenience is that it comes with Miniconda already installed in many flavors, so we
-don't need to download it. The first thing to do is go to your profile page on
-https://www.appveyor.com and enable building your repository.
+* [Getting the scripts](#getting-the-scripts)
+* [TravisCI (linux|mac)](#travisci)
+    * [Miniconda](#miniconda)
+    * [Github Pages](#github-pages)
+    * [Deploying to PyPI](#deploying-to-pypi)
+    * [Releasing](#releasing)
+* [AppVeyor (win)](#appveyor)
 
-The configuration is setup in an `.appveyor.yml` file. The
-`appveyor/setup-miniconda.bat` script configures and updates conda, creates a new
-environment, and installs dependencies on it. The dependencies are specified in
-`.appveyor.yml` through a variable `CONDA_REQUIREMENTS` that defines a requirements
-file.
 
-There are no deploy actions specified for AppVeyor. We'll use TravisCI to handle
-deploying the docs to Github Pages and builds to PyPI.
+## Getting the scripts
 
- See the sample `.appveyor.yml` configuration included in this repository.
+On the CI configuration script, clone a specific release of this repository:
 
-[![AppVeyor build status](http://img.shields.io/appveyor/ci/fatiando/continuous-integration/master.svg?style=flat-square&label=AppVeyor)](https://ci.appveyor.com/project/fatiando/continuous-integration)
+    git clone --branch=VERSION --depth=1 https://github.com/fatiando/continuous-integration.git
+
+Replace `VERSION` with the release you want to use, like `1.0.0`. See the
+[Releases page](https://github.com/fatiando/continuous-integration/releases) for a list
+of versions available and changes made in each.
+
+We use [**semantic versioning**](https://semver.org/) to mark our releases:
+
+* Major version number change (e.g. `1.2.1 -> 2.0.0`): Break in backward compatibility.
+  You will need to update your CI configuration to use this new version.
+* Minor version number change (e.g. `1.2.1 -> 1.3.0`): New features/options added
+  without breaking existing builds. You can update to the new version without changing
+  your configuration.
+* Patch version number change (e.g. `1.2.1 -> 1.2.2`): Fix a bug without breaking
+  existing builds. You can update to the new version without changing your
+  configuration.
 
 
 ## TravisCI
@@ -33,17 +49,6 @@ list.
 
 See the sample `.travis.yml` configuration included in this repository.
 
-[![TravisCI build status](http://img.shields.io/travis/fatiando/continuous-integration/master.svg?style=flat-square&label=TravisCI)](https://travis-ci.org/fatiando/continuous-integration)
-
-
-### Getting the scripts
-
-Clone this repository in the `install` or `before_install` steps in
-`.travis.yml`:
-
-    git clone https://github.com/fatiando/continuous-integration.git
-
-
 ### Miniconda
 
 Install and setup Miniconda by sourcing the `travis/setup-miniconda.sh` script.
@@ -61,8 +66,7 @@ Include this in the `install` or `before_install` steps in `.travis.yml`:
 It's a good idea to run `conda list` to print out a full list of packages
 installed.
 
-
-### Deploy to Github pages
+### Github Pages
 
 Our strategy is to have the documentation for different versions (marked by git
 tags) in different folder in the `gh-pages` branch. Docs built from *master*
@@ -162,7 +166,6 @@ You must also set the environment variable `DEPLOY_DOCS` to `true` in the build
 that you want to deploy. This is to avoid deploying more than once in case your
 testing using different package versions or OS.
 
-
 ### Deploying to PyPI
 
 Uploading source distributions and wheels to PyPI can happen automatically when
@@ -201,9 +204,27 @@ You must also set the environment variable `DEPLOY_PYPI` to `true` in the build
 that you want to deploy. This is to avoid deploying more than once in case your
 testing using different package versions or OS.
 
-
 ### Releasing
 
 Now you can make a release by simply tagging a commit with a version number.
 TravisCI will create a new folder in the HTML documentation and upload the
 built package to PyPI.
+
+
+## AppVeyor
+
+AppVeyor can be used to test the build on Windows (both 32 and 64bit). A very nice
+convenience is that it comes with Miniconda already installed in many flavors, so we
+don't need to download it. The first thing to do is go to your profile page on
+https://www.appveyor.com and enable building your repository.
+
+The configuration is setup in an `.appveyor.yml` file. The
+`appveyor/setup-miniconda.bat` script configures and updates conda, creates a new
+environment, and installs dependencies on it. The dependencies are specified in
+`.appveyor.yml` through a variable `CONDA_REQUIREMENTS` that defines a requirements
+file.
+
+There are no deploy actions specified for AppVeyor. We'll use TravisCI to handle
+deploying the docs to Github Pages and builds to PyPI.
+
+See the sample `.appveyor.yml` configuration included in this repository.