BEAST Development

Basic Workflow

You are encouraged to help maintain and improve the beast. Before doing so, please familiarize yourself with basic version control and Git workflow concepts. A good description of the standard fork-branch-pull workflow can be found here:

Some other useful guides are:

In short, the fork-branch-pull workflow for contributing to the beast project is:

  • Create your own ‘fork’ of the official beast repository

  • Create purpose-specific ‘branches’ off your ‘fork’

  • Make changes or additions within the branches

  • Contribute your modified codes to the beast project or share them with your collaborators via ‘pull requests’

  • Keep your fork updated to benefit from continued development of the official version and to minimize version conflicts

  • Resolve version conflicts as much as possible before sending pull requests

Development Install

If you plan on modifying the beast in addition to running the code, it may be useful to create a development installation. First, create a fork of the official beast repository and clone it:

$ git clone https://github.com/YourName/beast.git

Optionally, you can rename this cloned copy:

$ git clone https://github.com/YourName/beast.git beast-YourName

Set the value of the fork’s ‘upstream’ to the official distribution so you can incorporate changes made by others to your development fork. In the clone of your fork, run the following:

$ git remote add upstream https://github.com/BEAST-Fitting/beast.git

In order to run a development installation, navigate to the directory in your beast repository that contains setup.py, and run:

$ pip install -e .

Alternatively, you can perform a development install directly through Python with:

$ python setup.py develop

Adding Branches

  • Make sure you are in the directory for your fork of the beast. You will be on branch master by default.

  • Create and switch to a branch (here named beast-dev1):

    $ git checkout -b beast-dev1
    
  • To see a list of all branches of the fork, with ‘*’ indicating which branch you are currently working on:

    $ git branch
    
  • To ‘upload’ this branch to your fork:

    $ git push origin beast-dev1
    
  • To revert back to your fork’s master branch:

    $ git checkout master
    

Making Changes

It is recommended that branches have a single purpose; for example, if you are working on adding a test suite, improving the fitting algorithm, and speeding up some task, those should be in separate branches (e.g. add-test-suite, improve-fitting-algorithm and beast-dev1).

  • Switch to the branch you wish to work off of:

    $ git checkout beast-dev1
    
  • Make changes to the existing files as you wish and/or create new files.

  • To see what changes have been made at any time:

    $ git status
    
  • To stage any new or edited file (e.g., ‘newfile.py’) in preparation for committing:

    $ git add newfile.py
    
  • To add all edited files (not recommended unless you are sure of all your changes):

    $ git add -A
    
  • To ‘commit’ all changes after adding desired files:

    $ git commit -m 'brief comments describing changes'
    
  • Commit messages should be short but descriptive.

  • To see the status of your changed files:

    $ git status
    
  • To view any differences between a file and the last committed version:

    $ git diff PathToFile/filename
    
  • To undo all changes made to a specific file since the last commit:

    $ git checkout PathToFile/filename
    
  • To sync changes made to the branch locally with your GitHub repository:

    $ git push origin beast-dev1
    

Test Changes

It is a good idea to test that your changes have not caused problems. In the base beast directory the following commands may be run to do this.

Run existing tests, including a regression test against a full beast model run. Once the command below has finished, the coverage of the tests can be viewed in a web browser by pointing to files in the htmlconv subdirectory (which gets produced when the tests are run).

$ python setup.py test --remote-data --coverage

Make sure the documentation can be created.

$ python setup.py build_docs

The resulting HTML files are placed in the docs/_build/html subdirectory, and can be viewed in a web browser.

Submitting a Pull Request

Once you have changes that you’d like to contribute back to the upstream branch, you can open a pull request for review. Pull requests can be submitted at https://github.com/BEAST-Fitting/beast/pulls. If you push any commits to your origin repository in a development branch (beast-dev1), then a “Compare & pull request” button should appear at the top of this site. Briefly describe the changes/additions you made in the comments section and submit the pull request.

Staying up-to-date

The beast project’s official repository will be updated from time to time to accommodate bug fixes, improvements and new features. You can keep your fork’s master repository up-to-date with the following steps:

  • Switch to your fork’s master branch:

    $ git checkout master
    
  • Fetch the project’s up-to-date distribution:

    $ git fetch upstream
    
  • Merge the official (upstream) master branch with your fork’s master branch:

    $ git merge upstream/master
    
  • Sync this change with your origin repository:

    $ git push origin master
    

BEAST on Slack

There is a beast space on Slack. Email kgordon@stsci.edu for an invite.

Visualizing Repository Commits

The commits to the beast repository can be visualized using gource. This creates a movie showing the time evolution of the code and who made the changes.

Version created 22 Jan 2018: <http://stsci.edu/~kgordon/beast/beast_repo.mp4>

Command to create it:

$ gource -s .06 -1280x720 --auto-skip-seconds .1 --multi-sampling  --stop-at-end --key --highlight-users --hide mouse,progress --file-idle-time 0 --max-files 0  --background-colour 000000 --font-size 22 --title "This is beast" --output-ppm-stream - --output-framerate 30 | avconv -y -r 30 -f image2pipe -vcodec ppm -i - -b 65536K beast_repo.mp4