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.

TLDR: How to write a CHANGELOG#

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.)

Real world scenarios#

• React
• Moment.js
• Jest

Follow Semver#

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.

From https://semver.org

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.

Closing#

For mid to large sized companies it is very common to maintain internal libraries (i.e. npm packages for Javascript applications), so it is of the outmost importance that we manage them correctly since, although the audience is reduced, they behave very close to the Open Source model.

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:

The Cathedral & the Bazaar