How to create a Landlab release
Landlab development takes place in your own fork of the main Landlab repository. A fork is a mirror of the repository and is hosted on your personal GitHub account. You will use this fork for developing new Landlab features. Your changes will migrate to the core repository (for review and merging) by requesting that the main repository “pull” in your changes. This is known as a pull request and is facilitated through the GitHub website.
Note
For dev work, we actively recommend Anaconda over the Enthought Python Distribution, especially on Windows machines. This is because it ships with a working compiler already associated with Python, whereas the EPD does not. On a Mac, this is less important as the Xcode app (available through iTunes) gives you the necessary compilers instead - install it now if you don’t have it! If you choose to use the EPD on a Windows machine, however, you’ll need to install separately either Visual Basic or MinGW and successfully associate them with your Python install. Help on this process can be found here. But unless you’re really invested in Canopy and the EPD, uninstalling it and replacing with Anaconda is probably the more stress-free way to go.
Either way, you’ll need a working C++ compiler running alongside Python to be able to perform a full developer install. You’ll see errors referring to Cython if you don’t have working compiler when calling python setup.py develop.
You will only need to do this once for each project to which you want to contribute. Github has some great documentation on how to create a fork. We outline below the basic steps as applied to Landlab.
The following steps will create a fork of the Landlab repository under your github account.
Once completed, you will be redirected to the home page for your own copy of Landlab.
This is done from the GUI by:
This is done from the command line with the following commands:
> git clone git@github.com:your-user-name/landlab.git
> cd landlab
> git remote add upstream git://github.com/landlab/landlab.git
You can also clone your fork in the GUI directly through the website; navigate to the page for your fork on the web (UserName/landlab) and hit the “Clone in Desktop” button on the right hand side of the page. Make sure you have the GUI installed and set up on your machine before you try this for the most pain-free results.
Before you start: Ensure you have installed with Xcode from the Apple app store (macs) or installed a working C++ compiler on your machine (PCs) before proceeding with your developer install. You should also update your Python distribution! For Anaconda, use conda update –all (two dashes), and then separately, conda update setuptools (the second being essential!) from your terminal.
Note
This assumes you have never put Landlab on your machine before. If you’ve previously used pip to install Landlab, we recommmend you take that version off first. At a command prompt, use the command: pip uninstall landlab
Now that you have a working copy of the Landlab code on you computer, you need to install it. To install Landlab in developer mode run the following command from the root Landlab folder (it will be landlab with a small l and will contain setup.py):
> python setup.py develop
This installs Landlab on your computer in such a way that Python always imports Landlab from the working copy you just cloned. This ensures that any changes you make to your copy of the code is seen by Python the next time you import Landlab.
To uninstall your development version of Landlab (again from the root landlab folder) run the following command:
> python setup.py develop -u
With Landlab uninstalled, you will not longer be able to import Landlab from outside to root folder of your working copy.
To check you have correctly installed Landlab, run the Landlab tests. Do this by importing landlab in an interactive Python shell, then calling landlab.test().
From time to time you should fetch commits to the trunk that you don’t have in your working copy. You do this with the following command:
> git fetch upstream
Before making any changes to your code, you should create a new branch.
Update your mirror with any upstream changes you don’t have:
> git fetch upstream
Make the new branch:
> git branch name-of-branch upstream/master
> git checkout name-of-branch
You will probably want to choose a descriptive name for your new branch so that you and others will remember what it is you are intending to do with your branch (for example, bugfix-for-that-major-problem, or add-that-cool-feature).
If you want to keep your branches on you public GitHub page for Landlab (you probably do) you need to tell git to push changes to your github repo. This is done with the following command:
> git push --set-upstream origin name-of-branch
On your Landlab GitHub page you will now be able to toggle between your various branches to see the code you have committed.
The GUI also offers fairly simple, intuitive, and powerful control over branching and merging, for those uninclined to use the command line tools.
The easiest way to run the Landlab tests is to do so from inside the Python interpreter:
>>> import landlab
>>> landlab.test()
This will run a series of tests and print our the result of each test. If there are any failures, you can report that at the landlab issue tracker.
If you want to check how well you are doing, please look at our Landscape page. Landscape will grade the health of the landlab code with every push to GitHub.
Before merging any changes into the Landlab trunk, all unit tests (including doctests) should be passing. In addition, any new features added to Landlab should have an associated set of unit tests to verify that the new features are working properly.
Landlab uses Travis for continuous integration testing. The landlab page on Travis shows the latest testing results. A new set of tests are executed whenever any changes are pushed to the Landlab repository and with every pull request. We currently run test suites for Python versions 2.6, 2.7, 3.3, and 3.4.
Continuous integration for Windows is done on Appveyor and also tests with Python 2.6, 2.7, 3.3, and 3.4.
Once you send a pull request from GitHub, you will be taken to the Landlab pull request page and all unit tests are run. You will see the status of the unit tests next to your latest commit description. If you see a green check, all tests passed and your changes can be merged! However, if you see an ex there was a problem running the tests. If you believe your changes are responsible for the failures, please fix them until the tests pass. Note that you do not need to send a new pull request after committing for fixes. They will be added to the current pull request and the tests automatically rerun.
You can also run unit tests locally with the test-installed-landlab.py
script found in the scripts folder:
$ python test-installed-landlab.py
Note that this script will test whatever version of landlab you have installed, which may or may not be the one you are working on in your current working directory.
Get the latest upstream/master and go to the master branch. Remember, do not develop here. Always develop in a feature branch. Merge the lastest upstream master with your master:
> git fetch upstream
> git checkout master
> git merge upstream/master
Go to the branch on which you are developing and merge the lastest upstream master with your branch:
> git checkout <branch_name>
> git merge upstream/master
Fix the conflicts. Do this by hand or with a merge editor. This is where you decide how to integrate the conflicting changes. Since only you know what and why you made the changes you did, this can only be done by you:
> git mergetool
After everything has been fixed, commit the changes and push the changes to the repository. The pull request will automatically be updated:
> git commit
> git push
The Landlab development team will be happy to hear from you. Email one of us or create an issue request and we’ll try to resolve your problem.