Installing for developers and beta-testers

The overall process for adding code to OPS goes in 3 stages:

  1. Code is developed in a user’s fork of OPS.

  2. Those changes are merged into the OPS master via a pull request on GitHub.

  3. At some point, the master code is turned into a release.

For most users, code that has reached stage 3 is all that is needed. This is what the standard install provides. Those who want the access to features before they are released might be interested in code at stage 2. Installing that is described in the “developer install” section of the installation docs.

However, in rare cases, users might want to run the very raw code that is only at stage 1. There are a few potential reasons for this. First, perhaps you are developing new features, and want to use your own experimental code. Second, perhaps there is an experimental feature that isn’t ready for general use, but you want to try it out very early. Third, perhaps you’ve identified a bug, and we want to confirm with you that our fix does, in fact, solve your problem. For any of these cases, you’ll want to use the installation procedure described here.

If you will be writing code for OPS, you should fork OPS and do the developer install by cloning the repository of your own fork. For details, see the GitHub documentation on forking a repo.

If you won’t be contributing code (either you’re beta-testing or confirming a bugfix), you’ll first do a developer install, then add a a “remote” so you can access code in someone else’s fork. You’ll need to know which developer’s fork you’re using, and what branch the code you’ll be testing is on.

As an example, we’ll add a remote from the developer dwhswenson, and we will call that remote dwhs (this name is up to you, but it is common to use some short name such as the developer’s initials). Then we’ll check out a branch called cool_new_feature from that fork, and give it the local name dwhs_cool_new_feature. Again, the local name is up to you, but using the remote nickname and remote branch name make it easy to recognize.

git remote add dwhs http://github.com/dwhswenson/openpathsampling.git
git fetch dwhs
git checkout -b dwhs_cool_new_feature dwhs/cool_new_feature

In the git checkout command, the first thing after the -b is the local name of your branch, and the second is remote/branch_name.

With a developer installation (i.e., using pip install -e or setup.py develop), the code in the directory where you cloned the OPS repo is the code you’re running. So you can update to our more recent changes by running git pull. You can switch to another version of the code (like a release or the current master) by using git checkout to select the appropriate branch or tag.

We strongly recommend that users working in this fashion become familiar with git. Details like which branch you are in can make all the difference when it comes to identifying problems.

Quick bugfix/developer installation

In some cases, especially for one-time bugfix tests or for developers using continuous integration, it is useful to be able to quickly set up a developer installation in a separate conda environment. By creating a separate environment to test a specific branch, you don’t risk messing up your production environment. There are a few ways to customize the behavior of the conda_ops_dev_install.sh script to facilitate this.

If the environment variables OPS_ENV and CONDA_PY are set, that script will create a new conda environment with the name $OPS_ENV and using Python version CONDA_PY. For example OPS_ENV="ops-py37" CONDA_PY="3.7" bash conda_ops_dev_install.sh will install a developer version of OPS in the environment called “ops-py37” using Python 3.7. Note that if you source the script (instead of running it in a separate process), the new environment will be active. By default it will use the current environment, and keep the Python version at the same minor release.

You can also select a specific fork and branch to check out. For example, bash conda_ops_dev_install.sh dwhswenson experimental_feature would check out the fork at dwhswenson/openpathsampling, and install from the experimental_feature branch. By default it checks out the master branch of the openpathsampling fork.

Note that the conda_ops_dev_install.sh script currently requires that conda be importable. This means that conda needs to be installed in the environment that you start from. We recommend running this script from your base environment, where conda will be importable.