ISA API development

This page will document the development practices followed in the ISA-API development.

Branching and merging

When working on a new feature, fixing a bug, or making any other significant change, we encourage you to make branches as and when you work on any of these new additions or modifications to the code-base of a project. This benefits how we all work in a few ways:

• It gives you as a contributor a stable base to begin working on your changes since it should only be yourself (or a sub-team) working on the new branch
• Changes can be reviewed by project team members (and if ever necessary rolled back easily) on merging into the master branch. Practice with the branch-merge workflow is particularly essential when incorporating contributions from non-ISA-team people.

What about something like this? We should probably work off a "develop" branch while everything is in flux, and use "master" for releases. See the lovely diagram in the aforementioned link.

Branch Naming Conventions

We follow the branching conventions described here

Use "grouping" tokens in front of your branch names.

group1/foo
group2/foo
group1/bar
group2/bar

Currently we've used feat/feature_name (feat being the grouping token). Other suggested tokens might be test (e.g. test/test_name) for implementing tests, bugfix (e.g. bugfix/issue_14 or bugfix/issue_shortname) for implementing bugfixes, junk (e.g. junk/my_experimental_branch) for branches intended to throw away.

Commit messages

Commit messages should be reasonably informative. They should describe what was changed (which area/subsystems of the code, not the files themselves, as that information is already displayed by git), in which way they were changed and the rationale behind the change. Any known bugs or limitations should be described, as well which other subsystems are impacted, if any.

If there's an associated issue/ticket, it should be mentioned.

• Make the first line relatively short (maybe less than 50 characters), as a description of what the commit does. Use action words, as the commit makes the change on the code (even though instinctively the change has been made already) - e.g. instead of 'Added tests for validation feature' say 'Add tests for validation feature'
• Following line should be empty
• Provide a short line or two with a high-level description of what has been implemented or changed, with the rationale behind the change. Refer to a specific issue # or reference, whether it's in the GitHub issue tracker or elsewhere
• Follow this with a bulleted list (using *'s) With a short description of each change in the commit
• Finally, describe with a line or two any consequential impact on the behaviour of the code.

Code conventions

Coding conventions and standards are essential - although code is written to instruct machines, code should also be written so that humans can understand it! In an ideal world, code should also be self-documenting so that we don't have to write documentation yet again somewhere decoupled from its context.

Doing things the 'Pythonic' way - in the spirit of the Python language - is encouraged, as it purports a high-level of readability in code. For example, sometimes the simplest way is the best way to express some statements, rather than the 'clever' way.

• Pythonic code style guide
• PEP8 styling
• Naming classes, methods, parameters and variables are key to readability. Good names save time when trying to a piece of code and when debugging and refactoring. This includes when reading your own code and trying to remember what you intended it to do (if it was a long time ago for example)