Versioning, incrementing and updates

[henry-ngo]

This issue documents our current approach to versioning and incrementing. It can remain as an open issue as we work on the next few updates, discussed here, and then incorporated into something like CONTRIBUTING.md when it's more stable.

Versioning scheme

We are following semantic versioning 2.0.0. Their summary:

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards compatible manner, and
• PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

When to merge into main and increment version.

Every merge into main should be a version increment. If staging multiple merges for a future version increment, keep these staged changes in a development branch.

Merges into the development branch destined for a version increment should have NEWS.md updated so that we track the changes. When we merge into main and increment version, we can trim NEWS.md to combine related items and/or just pick the most important changes to communicate.

Clarification: For now, as of v1.0.1 (PR #13 and #14) we decided that a change to fix an error in documentation is a "bug fix" (i.e. a PATCH version change).

Version increment workflow

This would be a merge into main from a development branch. A reminder checklist of things to do as part of the PR to merge into main

1. Review NEWS.md and update to reflect what we want it to say (may need to trim, edit, summarize notes from previous commits)
2. Update the DESCRIPTION metadata file (date and version number)
3. Update the README.Rmd "Citation" section to reflect version number and if necessary, new year of publication
4. If necessary, update the README.Rmd "License" section to reflect the new date (year)

After merging the PR into main and checking for errors, we should:

5. Publish a "Release" for this new version number. This will also create a git tag.