git Workflow

One of the main advantages of git (vs svn/cvs) is branches/forks. Some of the advantages of github are "issues" and their "assignees", pull request "reviewers". All this benefits situations with many simultaneous developers and fast changes to allow for more tractable software development.

branches

Branches/forks are easiest if used temporarily, for smaller projects with well-defined goals. Your own neverending branch for all your development, spanning multiple topics, can be a headache if it gets too far behind its mother branch.

general policies

• development is the main branch for development. No one works on master!
• No direct commits, only pull requests, not even "experts"!
• No pull requests should be accepted by the requester, not even "experts"!
• Pull requests can/should also tag a reviewer and assignee.
• All releases are done on master, pre-releases can be done on development
  • Tags with an "a" in their name are from master branch
  • Tags with a "b" are from development
• development branch is merged into master by the software librarian
  • upon decision of software leader, e.g. for a new release
• All commits should have useful messages
  • e.g. just 'minor' or 'updated [my detector]' or 'cleanup' are pretty useless commit messages
  • concisely state what was really changed
  • can/should reference the package/dir that was upgraded
  • note that you can also use multiple commit messages (-m) on one commit

These policies all serve at least to announce the changes, ideally to put some more eyes on it, hopefully to make development more transparent to all and easier to catch bugs before they propagate.

workflow

1. fork the repository to your github account, clone your fork, switch to development branch
2. make changes, complete task, test changes
   • including running some/all builtin validation tests
   • and surely make sure it actually compiles!
3. submit pull request via github website
   • from your fork's development branch, to the real development branch
4. request accepted/amended/commented/rejected by someone else
   • if accepted and merged into main branch, maybe/probably just delete your fork

basic git commands

• fork the repository to your github account via github's website
• clone your fork:
  • git clone https://github.com/githubUserName/clas12-offline-software
• this is the most important git command; run it regularly and learn what its output means before doing anything else:
  • git status
• switch to the development branch:
  • git checkout development
  • Note, the default branch is now development so this command isn't necessary unless you switched branches. Run git status to check what branch you're working on.
• commit changes in your local repository:
  • git commit -m 'MyEngine: code cleanup' path/to/cleanedup/files
• push local changes to your remote repository:
  • git push origin development
• pull requests via github's website

github "issues"

• anyone can make an "issue", and "assign" it to someone
• one model is that each issue is addressed on one unique branch of the same name, and the corresponding pull request's comments can/should say whether issue is resolved, and issue closed/amended accordingly