Development workflow

This is a brief overview of development workflow.

Currently we have three long-living and (possibly) multi-authored branches:

• 'master';
• 'pyDKB' (this branch still exists, but is not active; all changes to pyDKB library are done in PRs directly to master);
• 'api'.

To introduce some changes to the multi-authored branch:

1. Create a separate branch from the goal branch (in a fork repository or in the original one).
2. Make your changes (bug fix, new feature or module development, README change, storage data scheme update, ...).
   Keep in mind:
   • one commit for one logical change (say, typo fix or indent change, new functionality or refactoring, ...)
   • log message should be clear and understood: 50/72 rule (commit summary + more detailed description, if necessary)
   • all the commits should be related to one general idea (so don't put "Stage XX: bug fix", "Stage YY: new functionality" and "README: typo fix" commits to one branch, even if the Stage XX bug was detected during Stage YY development, and at the same time you accidentally ran into the typo)
3. Review changes before every commit:
   • git status to see files staged for the commit, changed ones, etc
   • git diff --staged -- to see the changes, staged for the commit
   • git diff -- to see the changes, left unstaged
   • git add --patch <file> -- to stage only a part of changes, introduced in the file
   • git commit shows the list of added/removed/modified files staged for the commit and another list for unstaged ones (as a comment in the editor opened to write the log message)
4. Review the development history every time before push:
   • git log - to see the history
   • git rebase -i <commit> - to (locally) rewrite the history the way you like (reorder, join, split or delete commits)
5. Push your changes to the remote branch (created in Item 1).
6. When all the changes are done, create a pull request for the branch you want to introduce the changes to.
   Keep in mind: merge strategy for all requests is Merge or Rebase, not Squash.
   It means, that the whole branch history will be duplicated and stored as a part of the repository history. If necessary, a new branch can be created to pick a set of needed commits and skip redundant ones.
7. After the request is reviewed, the author might be asked to make some additional changes.
   Make the changes in the same branch, from which the request was created. New commits will appear in the request automatically.
8. The commits will be merged to the original branch as soon as the request is approved.
9. When the pull request is merged, the source branch (created in Item 1) can be removed.