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:

https://gist.github.com/Chaser324/ce0505fbed06b947d962

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

beast follows the same workflow and coding guidelines as Astropy. The following pages will help you get started with contributing fixes, code, or documentation (no git or GitHub experience necessary):

Installation¶

If you plan on modifying the beast in addition to running the code, it may be useful to create a development installation by following the Installation for Developers instructions.

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
```
If you add a file type in the beast/ folder that’s not typically included (e.g., txt or png), you also need to list it in the [options.package_data] section in setup.cfg. Even if the file exists in the repository, adding it here is necessary for it to be included when the package is built.

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).

$ tox -e test -- --remote-data --coverage

Make sure the documentation can be created.

$ tox -e 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.

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

Navigation