suppress changelog's for prereleases?

[semantic-release]

suppress changelog's for prereleases?

[pmizio]

For in my team I introduced following solution:

Rename .releaserc to release.config.js and create your config around this snippet:

const branch = process.env.CI_COMMIT_BRANCH

const config = {
  branches: ['master', { name: 'dev', prerelease: true }],
  plugins: ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator'],
}

if (config.branches.some(it => it === branch || (it.name === branch && !it.prerelease))) {
  config.plugins.push('@semantic-release/changelog', [
    '@semantic-release/git',
    {
      assets: ['CHANGELOG.md'],
      message: 'chore(release): ${nextRelease.version} \n\n${nextRelease.notes}',
    },
  ])
}

module.exports = config

CI_COMMIT_BRANCH env variable is populated with branch name by our CI provider which is GitLab, if you using something else feel free to grab this from another source
I hope it help someone ;)

[bradennapier]

I think it makes sense to have a setting to only generate the changelog on certain branches whereas the release notes would indicate every release and the notes for that release.

That way the CHANGELOG.md is a pure representation of the changes to the main release whereas the release notes would be the release-by-release view

[1nVitr0]

I think this is definitely relevant. Prerelease branches often receieve updates frequently and in smaller increments than release branches. As prereleases are often for major releases all those little changes are written under giant capital headings for each prerelease.

This can make reading the changelog extremely cumbersome, especially if all the changes are then duplicated in the actual release. It would also be enough to provide a separate changelog file for prereleases, as they are only interesting for a select group of users.

[mtrezza]

This should already be possible by creating a custom handlebar template and suppressing the output in the change log writer if the release is a pre-release. It would even be possible to write them into their own section of a change log file and add a TOC to navigate to whatever is important to the user.

https://handlebarsjs.com/
https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#readme

Another possibility is to create a separate change log file for each branch, and link to them in the common CHANGELOG.md file. That also prevents merge conflicts when merging between different release branches. In GitHub you can get the current branch name as env variable and then change the output file:

const ref = process.env.GITHUB_REF;
const branch = ref.split('/').pop();

['@semantic-release/changelog', {
  'changelogFile': `CHANGELOG_${branch}.md`,
}],

[bryanlarsen]

For us, it appears about 5 times in the changelog. First in the feature prerelease branch, then in the story prerelease branch, then in the integration prerelease branch, then in the rc prerelease branch and then it finally hits master. It seems excessive, but semantic-release is a big part of the automation making this process almost transparent to developers.

And usually it's a lot more. The integration branch is what new feature/story branches are forked off of, so anything that hasn't hit master at fork time gets repeated in dozens of other branches.

[yinzara]

+1 Absolutely needs to be a feature.

My workflow is nearly identical to this.

A feature starts in a feature branch (initial prerelease with first instance of changelog) which is published and distributed in special environments designed to test new feature. This is where any manual testing takes place so is the first touchpoint of the QA team. We use Semantic release prereleases to help testers know when a new version of a feature they're testing is available.

It gets merged to develop when complete (duplicated in the "next" prerelease) and deployed to a shared environment. This is the next point QA may test the feature in conjunction with other recently developed features. We use semantic release prereleases to inform testers that there are new features in the next realease.

When a release is required, develop is merged to release to verify before production (duplicated in "release candidates"). Here QA receives another copy of the application with all features and bugs ready for the next release. We use semantic release prereleases for their primary intent, for release candidates.

Finally merged to master when released (duplicated again).

There should be a way to use the prior release version to determine the last entry in the log that corresponds to it and removes all those changelog entries before appending the generated changelog since that release otherwise every message will be duplicated for every stage of the SDLC (4 copies of each message in my case).

[pvdlg]

What would be the point of that? What's the problem with having a changelog entry for a pre-release?

[pvdlg]

Closing as no answer was provided

[mikecbrant]

+1 on need to address this issue (probably before prerelease functionality is out of beta).

Since adopting use of prerelease, we are finding that default behavior of this module is problematic as you begin to get prerelease notes intermigled with (duplicate) release notes once the changes are release into master release branch.

This causes us to have to manually correct changelog files after the master release :(

I guess alternately, rather than just having an option to potentially turn of this plugin for prerelease, the release-notes-generator could be made to modify prerelease changelog entries into master release entries rather than just simply appending the duplicate master release notes into the changelog. My guess is that this would be more complex to implement though.

[pvdlg]

If a feature is released as part of a beta, and then later released as part of a normal it will appear twice in the changelog. Once under the beta and once under the normal release.

How is that a problem?

That's an accurate depiction of what happened...And as a user reading the changelog, I would read only the content of the version I'm using. So if I'm on a beta version I would read the beta release changelog, and I would skip those if I'm on a regular version.

[pvdlg]

Why do you have so many pre-release branches?
Do you really need to publish a release at each of those steps?
The objective of a pre-release is to publish a version that will be used by a subset of users. Do you really have users using all those different version?
If not then don't release those. From the list you provided it seems only rc might actually be used by users. If it's the case release only from rc and not from integration and story.

[bryanlarsen]

Every single one of those prereleases is live on the interwebs, and semantic-release is a key part of making that easy. This makes it extremely convenient for reviewers.

And every prerelease is published and used by a developer. If module X is used by service S, they're often developed in parallel, so service S needs a lot of intermediate versions of module X at every stage.

[DiegoRBaquero]

Need this too

[zanona]

I believe that one use case would be nightly builds: having the changelog updated every day, may indeed become a problem if it goes to nightly > alpha > beta > rc > stable, as it would create so many duplications that it could make the changelog difficult to read?

I often version each one of these releases to they can be identified, rolled back to, if needed. So this is where I'd use the version generated by the semantic-release in order to release those builds with unique version numbers, which is really helpful.

Sorry, hopefully I'm not missing something obvious here, but requesting that the changelog plugin ignores specific branches seems a sensible request to me?

Perhaps bumping the version number for each pre-release may not be a good idea at all, in which case It would be interesting to learn about a possible workaround to uniquely identify each one of those builds?

I hope this can be reconsidered. :)

[albert-a]

I just remove all prerelease entries from the changelog on release branch with sed:

    ["@semantic-release/exec", {
        "prepareCmd": "test ${branch.type} != release || sed -i '/^## \\[/h;x;/^[^]]*-/{x;d};x' CHANGELOG.md"
    }],

So for users there are no unnecessary prerelease entries. For beta testers they are. Everyone is happy.