Whether you are working on an open source library or an internal private library you should master the art of CHANGELOG.
This is a fundamental not-coding part of maintaining libraries and enables consumers to understand what they can expect when moving from version to version.
This is a great resource to share with your teammates inside your company so hopefully you can all have a common ground when maintaining internal libraries.
Keep in mind:
- your primary audience are humans that consume your library, think of them when writing the CHANGELOG.
- it is sorted by last entry first (descending order)
- each entry has a date and a version number
- follow Semver
each entry should answer:
- what was added, changed, deprecated, removed, fixed, etc
- are there any breaking changes?
- Nice to have: any dependencies updates (dependencies are becoming more and more complicated so documenting any important changes here might give your consumers clues about any unexpected behaviours)
Keep a CHANGELOG is a great standard you can follow, make sure to read their docs thoroughly but here is an example following their suggested format.
Have in mind that this is a template, not all subsections
### need to be added.
Component X refers to software component, probably identify it by its directory path
or by its name or by any non-abiguous id that is obvious to consumers.
**BREAKING** needs to be added to any changes introduced that are not backwards compatible,
make sure to follow Semver (see next section).
## [Unrelease] All changes that will be added in the next version ## [1.0.0] - 2020-05-04 ### Added - New feature A in component B - ... ### Changed - **BREAKING** Component C now does thing D - ... ### Removed - **BREAKING** Component E has been removed ### Deprecated - Component F has been depreacted and will be removed in next major release ### Fixed - Component G now handles scenario X correctly by doing thing Y ### Security - Security vulnerability in Component H has been fixed (Probably add more details.)
Unless you have very strong reasons and opinions for not following Semver I suggest you follow it. It is a great standard tool used across a variety of ecosystems with clear semantics and documentation.
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.
The combination of properly implemented Semver and properly implemented CHANGELOG is a very powerful solution for maintaining libraries.
Most of the things we go through this post have been observed from the Open Source world, which brings me to a bonus conclusion: You can use the Open Source model as a role model for your company’s internal ecosystem
You can explore this concept in the following recommended book: