Create change log in docs

[rwood-97]

Is your documentation update related to a problem? Please describe. Some big changes have been made to the code since v0.3.3. We should have a file in the docs which logs these and makes sure users can find which version to use to revert back to deprecated features.

This could be added as .md file in the code or as .rst in the docs

[kallewesterling]

$ git log --oneline --decorate --color

would output something like this:

Might be a good start for changelog (but: we need to then start writing more verbose git commit messages...) -- also, see below (under "keep a changelog") for why this might not be a good reason

Some good resources:

• keep a changelog: Don’t let your friends dump git logs into changelogs.
  • Changelogs are for humans, not machines. (Don't use commit log diffs as changelogs)
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.
  • Types of changes:
    • Added for new features.
    • Changed for changes in existing functionality.
    • Deprecated for soon-to-be removed features.
    • Removed for now removed features.
    • Fixed for any bug fixes.
    • Security in case of vulnerabilities.
  • Keep an Unreleased section at the top to track upcoming changes (reduces effort to maintain changelog)
  • Use ISO standard for dates (2024-07-09)
  • Call your file CHANGELOG.md (make it easier for end users to find notable changes)
• 11 Best Practices for Changelogs
  • Start with the latest version
  • Determine the versioning strategy: semantic, incremental, date-based, codename, alpha-beta-rc
  • Date each release: long, short, numeric or ISO 8601
  • Use clear and concise language
  • Categorize changes: added, changed, deprecated, and removed
  • Provide links to relevant resources: developer documentation and technical tutorials to blog posts and webinars
  • Use a consistent format
  • Provide information about end-user impact: addresses user concerns and foster confidence
  • Use bullet points
  • Review and update regularly
  • Automate changelog generation
• Changelog
  • Create a CHANGELOG.md file or use GitHub releases
  • Include version, release date, and a list of grouped changes: new features, bug fixes, breaking changes
  • Separate large releases: When most releases are large consider splitting the changelog into multiple files
  • Automate changelog generation (if you have a large project and/or a strict format of commit messages)
  • Keep changelog up to date
  • Show version and date in release heading
  • Group similar changes by category: fixed, added/new, changed/updated, deprecated, removed, docs
  • Highlight breaking changes and deprecations (anything that will be removed in future releases)
  • Focus on changes that impact users
  • Credit external contributors

[rwood-97]

Hi,

I think it could be time to start a 'dev' branch for small PRs between versions, then each version change is a dev -> main merge. This would make it easier to manage changes per version in the changelog.

At minimum for this issue, we should:

• [ ] add a to do for "Update changelog" to our PR template to encourage adding changes to a changelog
• [ ] add some info about how the changelog works (e.g. what to track in it, what is too small to worry about) and how to go about updating the changelog in our docs
• [ ] consider the 'dev' branch approach

We may also want to have some definite rules re. version numbering. I try to do semantic versioning but am not totally sure if I'm doing it correctly.

[kallewesterling]

I like the idea of creating a dev branch where we work on new releases, and use main for stable releases. (It could even be called stable if we want, or have the version number as the name...)

I think we definitely, in our ways of working -- or the developer's corner -- should have something about how the changelog works. I also love the idea of adding something to the PR template... We might want to split these out into different issues...

[rwood-97]

Yep sure, should we do docs/adding to PR template as part of this issue and then separate ticket for dev branch?

[kallewesterling]

I think the dev branch, we can just do... Split off main now.

Then we can add 2 issues: (a) updating the docs with workflow, and (b) adding PR template language.