How to Contribute

Contributing to CalPack can come in many forms including:

  • Testing
  • Documentation
  • Developing New Features and/or Fixing Known issues
  • Reporting Issues

Don’t feel like you need a specific amount of experience to contribute. Simply reporting an issue is contributing! In order to develop some of the features within CalPack some knowledge of ctypes is needed.

GitHub, Issue Tracking and Branching

Development of CalPack is done within GitHub. Any issues that are encountered or reported are tracked within GitHub’s internal issues tracking.

When developing code we use the following 3 major branches:

  • prod - production level code. This is where relases are tracked. It’s from this version that the pypi repo is updated. Only integ branch can be pushed to this branch. This branch requires admin approval for Pull Requests to be merged.
  • integ - integration level code. This is nearly a clone of prod. The dev branch can push to this branch as well any hotfixes (small critical changes that need to be deployed immediately.
  • dev - Main development happens here. Any Pull Requests from developers should be against this branch.

Any new Pull Request should be against the dev branch. When working on specific features, branch from the dev branch using the branch name feature/<feature-topic>. When a critical issue is identified that needs to be fixed immediately, branch from the integ branch using the branch name hotfix/<hotfix-topic>

When we do releases, brances from the integ branch will be done using the branch name v<version number>.

After each push into any branch a Travis CI and Appveyor to run tests on differing python versions on linux and Windows. After successfully passing the unittests coverage results are uploaded to coveralls and codacy.

Warning

Before a Pull Request into the prod branch, all unittests and QA checks from Coveralls and Codacy have to pass first.

Sprints and Sprint Planning

While issues are tracked within GitHub, we additionally use ZenHub for prioritzing and planning future development of CalPack. For instant message communication we use slack. To be invited to the channel send a message to superuser<dot>kronos<at>gmail<dot>com.

Sprints typically run for 2 weeks at a time.

Developing code

The best way to start developing is to look through the issues listed in the issues page of GitHub. When creating new features or changes that affect the code, it’s imperative that unittests are updated as well. This may require the creation of new unittests. Any new tests that are implemented or old tests that have changed, need to go through a review with at least another CalPack developer.

We try to use a TDD approach to development of new features. Tests should be written first and then the features implemented. However this isn’t always necessary. If you decide to create a new feature or make changes to the code, please add any additional tests that will ensure the quality of the code you’ve created.

Documentation

Documentation is done using Sphinx and reStructured Text.

Testing

Even though developers should be creating unittests along with their code, additional testing may be required to ensure that the overal functionality is preserved. Additional tests are always welcome so long as they provide value added to the testing of the code. Duplicate testing should be avoided and will be rejected during review if found.