CHANGELOG.md content for release notes

[eMarek]

I am reading change log docs and usage examples with release-it package. Maybe I don't understand it well enough or maybe the way I use change log is a bit different then others.

My workflow is next. I am following the "rules" of Keep a Changelog. During the process of development we (I and my team) manually update the CHANGELOG.md file. I really don't want to have commit logs inside there. Many times commit logs from different developers are just a pure trash. That's why I prefer to have manual entries in CHANGLOG.md file. This way even project managers are able to understand them. Commit logs are too technically deep for them. Okay anyway. Right before a release our CHANGLOG.md file looks something like this (an example):

# Changelog

## [Unreleased]

### Added

- Added support for releasing app with `release-it` package.

### Changed

- Default button colors changed from red to blue.

### Security

- Updated vulnerabe package.

## [5.6.0] - 2020-05-02

### Changed

- The `pipeline` tag does not trigger pipeline and docker build anymore.

### Removed

- The `master` branch was removed. Replaced with `release` branch!

## [5.4.1] - 2020-05-01

### Fixed

- Critical bug breaks the app when submitting the form.

## [5.4.0] - 2020-04-26

### Added

- Just some README instructions.

### Changed

- Index HTML with one more paragraph.

As you can see my release notes are already prepared when I am making a new release and I want to use them. Actually, to be more precise I would love to have 2 things:

• Line with ## [Unreleased] text to be replaced with ## [5.7.0] - 2020-05-05 (so new releasing version and today's date) and committed and pushed alongside with releasing new version.
• This section

  ### Added
  
  - Added support for releasing app with `release-it` package.
  
  ### Changed
  
  - Default button colors changed from red to blue.
  
  ### Security
  
  - Updated vulnerabe package.
  

  to be used as GitLab release notes.

Is this possible to achieve this workflow with release-it package or not?

[eMarek]

I wrote a plugin:

const { Plugin } = require('release-it');
const fs = require('fs');
const path = require('path');
const moment = require('moment')

class KeepAChangelog extends Plugin {
  constructor(...args) {
    super(...args);
    if (!this.options.filename) {
      throw Error('Missing filename!')
    }
    this.changelogFile = path.resolve(`${this.options.filename}`);
    this.changelogData = fs.readFileSync(this.changelogFile, 'utf-8')
    this.unreleasedTitleRaw = 'Unreleased'
    this.unreleasedTitle = `\n\n## [${this.unreleasedTitleRaw}]\n\n`
  }
  getChangelog(latestVersion) {
    const hasUnreleasedSection = this.changelogData.includes(this.unreleasedTitle)
    if (!hasUnreleasedSection) {
      throw Error(`Bad changelog! Missing ${JSON.stringify(this.unreleasedTitle)} title in ${this.options.filename} file.`)
    }
    const previousReleaseTitle = `\n\n## [${latestVersion}]`
    const hasPreviouReleaseSection = this.changelogData.includes(previousReleaseTitle)
    if (!hasPreviouReleaseSection) {
      throw Error(`Bad changelog! Missing changelog for previous release ${latestVersion} in ${this.options.filename} file. It should be titled as ${JSON.stringify(previousReleaseTitle)}.`)
    }
    const start = this.changelogData.indexOf(this.unreleasedTitle) + this.unreleasedTitle.length
    const end = this.changelogData.indexOf(previousReleaseTitle)
    const releaseChangelog = this.changelogData.substring(start, end).trim()
    if (!releaseChangelog) {
      throw Error(`Bad changelog! There are no entries under "${this.unreleasedTitleRaw}" section in ${this.options.filename} file. Fill it up!`)
    }
    return releaseChangelog
  }
  bump(version) {
    const todaysDate = moment().format('YYYY-MM-DD')
    const releaseTitle = `\n\n## [${version}] - ${todaysDate}\n\n`
    const newChangelogData = this.changelogData.replace(this.unreleasedTitle, releaseTitle);
    fs.writeFileSync(this.changelogFile, newChangelogData)
  }
}

module.exports = KeepAChangelog;

Save it as keep-a-changelog.js and feel free to use it as:

{
  "plugins": {
    "./keep-a-changelog.js": {
      "filename": "CHANGELOG.md"
    }
  }
}

[webpro]

That's awesome, @eMarek! There is https://www.npmjs.com/package/@semabit/release-it-bump-keepachangelog but it seems unmaintained.

The current solutions offered by release-it and/or plugins are all based on the Git commit history (basically git log), so they would not help you indeed.

I think your plugin is very useful. I'm sure you are not the only one keeping a changelog like this! Maybe you want to publish your plugin (github/npm)? I'm happy to take over the idea and move it to e.g. release-it/keep-a-changelog. But it's obviously your idea, so just let me know.

[eMarek]

Yes, please move it to release-it/keep-a-changelog. It suits me. This way I don't need to maintain it separately for each of my projects, but it will be there on one place ready to use for everybody. I will leave you a pull request if I will have any needs.

[webpro]

I've released https://github.com/release-it/keep-a-changelog. Please let me know what you think, how it works!

[eMarek]

Looks good. Thanks!