Recommended Git Workflow

Our recommended Git/Github developer workflow for versioning and tagging is as follows:

1. Create a development branch and switch to it, e.g.  git checkout -b feature/cool_new_feature
2. Add your developments, commit and push these changes.

git add -A  
git commit -m "Add <foo> so it can do <bar>"
git push origin feature/cool_new_feature

3. Submit a Pull Request (PR) on GitHub and go through the review process.
4. Once changes are approved, the maintainer decides on the major/minor/patch version increment (e.g. 1.3.0)
5. The developer updates to the agreed version in DESCRIPTION and updates NEWS.md, e.g.
   usethis::use_version(which = "minor", push = TRUE)
   
6. The pull request is merged to the main branch
7. The commit (let’s say the SHA is 1234567) is tagged with 1.3.0
git tag 1.3.0 1234567
git push origin 1.3.0

Graphically, this looks as follows:

flowchart TB
    mb(["Main Branch"])
    cdb["Development Branch"]
    ca["Changes added\nChanges committed\nChanges pushed"]
    cr{Code Review}
    vi[Version incremented]
    ta[Tag latest commit]
    mbu([Main Branch updated])

    mb --"git checkout -b feature/cool_new_feature" --> cdb
    cdb --"git add -A\ngit commit -m 'Add <foo> so it can do <bar>'\ngit push origin feature/cool_new_feature" --> ca
    ca --"Github: Make Pull Request"--> cr
    cr --"Accept changes\nusethis::use_version(which = 'minor', push = TRUE)\nUpdate NEWS.md"--> vi
    vi -- "Pull request merged to main" --> mbu
    cr --"Reject changes"--> cdb
    ta <-."git tag 1.3.0 1234567\ngit push origin 1.3.0".-> mbu

    linkStyle default stroke:lightgray 

Note that this assumes that a single change would warrant a package version increment. If changes are smaller they can instead be merged into a separate branch e.g. development, when there are enough small changes, or there is also a bigger change, this development ‘holding’ branch can be merged into main following the steps from number 4.