Editing Changes.md

Changes.md stores a comprehensive log of changes for all versions of Gaffer. It is automatically included in the documentation and forms the notes that accompany each release. The primary audience for Changes.md is the end user, be it an artist or a tools developer. It is not a commit log.

Editing Guidelines

• When a commit results in a user-visible change, update Changes.md appropriately in the same commit. Rationale :
  • Changes.md will always be in sync with the code in the repository, so we can release at any time.
  • All subsequent merges/reverts/cherry-picks will automatically keep the change log in sync.
  • We can use git blame to jump from change log entries to the code changes they are associated with.
• Put your edits in an appropriate section :
  • Features for significant new features.
  • Improvements for incremental improvements to existing features.
  • Fixes for bug fixes.
  • API for API changes.
  • Breaking Changes for backwards incompatible changes.
  • Build for build changes, such as a change in a library version.
• Start each entry with the name of the relevant user-facing component, followed by a colon. Bear in mind that this is often not the same as the component at the code or API level. For instance, "Viewer :" is more appropriate than "SceneGadget :" or "SceneView :".
• If a single component has multiple changes, represent them as a markdown list.
• Place the most significant edits at the top of each section.
• Keep related edits adjacent to one another where possible.
• Edit pre-existing related entries where necessary to avoid redundancy or improve clarity.
• Reference relevant issues in parenthesis (#100).
• If in doubt, follow existing precedent from Changes.md itself.

Conflicts

Changes.md is a significant source of merge conflicts, because it is touched by so many individual commits. We have tried and/or considered various alternative approaches to direct editing, but all have downsides of their own :

• They tend to break the direct link between commits and change log entries.
• They tend to mean that Changes.md is not always up to date, leading to misleading logs for nightly builds and PR builds.
• They make it harder to suggest edits during code review or provide fixups after merging.
• They make it harder to maintain a useful ordering and to combine/edit related entries.

When conflicts arise, please either rebase your PR to fix them or leave "Allow edits from maintainers" checked when making your PR, so a maintainer can fix them for you.