Skip to main content

Changelog

Why?​

  • Documentation of Changes: It provides a detailed record of all modifications, enhancements, and fixes made to the software over time. This documentation helps developers, users, and other stakeholders understand what changes have been implemented in each version or release.
  • Communication and Transparency: Changelogs act as a communication tool between developers and users, offering transparency about the evolution of the software. Users can see what has been improved, fixed, or added in a new version, enhancing their understanding of the product.
  • Bug Tracking and Issue Resolution: Changelogs often include information about resolved issues, bug fixes, and improvements. Developers and QA teams can refer to the changelog to track the history of specific issues, aiding in future debugging or troubleshooting.
  • Versioning and Release Management: Changelogs are essential in version control. They assist in managing different software versions, making it easier to identify changes between versions, and ensuring consistency in the release process.
  • Historical Reference: Changelogs serve as a historical reference for developers, providing insights into past decisions, implementations, and feature introductions. This historical context can be invaluable for understanding the software's evolution and making future development decisions.
  • Customer Support and User Engagement: For customer support teams, a changelog can be a useful resource to understand recent changes and help users troubleshoot issues or adapt to new features. Additionally, informing users about new functionalities or improvements via a changelog can increase user engagement.
  • Semantic Versioning: Changelogs help in semantic versioning, which is a crucial aspect of version control. By documenting changes in a structured manner, it becomes easier to determine the appropriate version number for each release, understand the changes between versions, and make the right decisions about the current release flow (what should be release for each part of the system, in which order, etc.).

How?​

  • Basic convention - Keep a Changelog
  • I recommend creating a changelog notes for each of your project packages on each PR to have a clear and informative history of code changes.
  • Split your changelogs! I suggest creating not only a development changelog, but an end-user one too, e.g. separate changelog file inside the Stroybook. Your customer, end-user, etc. doesn’t need to know anything about the code changes, but it would be useful if they could have something like a product changelog with all information about product changes, new feature development, and minor or major changes.
  • Save your time - use the existing tools:

Semantic Versioning​

Read the original Semantic Versioning specification.

Changes types for libraries, backend API, etc.:

  • MAJOR - these are breaking changes that are not backwards compatible. Examples are: renaming a public class, adding/removing a non-optional parameter from a public API, or renaming an variable or function that is exported.
  • MINOR - these are changes that are backwards compatible (but not forwards compatible). Examples are: adding a new public API or adding an optional parameter to a public API
  • PATCH - these are changes that are backwards and forwards compatible. Examples are: Modifying a private API or fixing a bug in the logic of how an existing API works.
  • NONE - these are changes that are backwards and forwards compatible and don't require an immediate release. Examples are: Modifying dev tooling configuration like eslint.

Changes types for frontend apps:

  • MAJOR - the same as previous specification, but including some other examples that intuitively are MAJOR changes: this would include significant redesigns and things that somehow “start a new era”, as I call it.
  • MINOR - the same as previous specification, but including the fact of integration with backend API: if you start using some API that was not used before, it's a MINOR change.
  • PATCH - the same as previous specification.
  • NONE - the same as previous specification.