feat: creating specifically for conventionalcommits.org

[bcoe]

@stevemao I'm starting work on a preset that will be tailored specifically towards https://www.conventionalcommits.org/en/v1.0.0-beta.3/.

In the process of doing so, based on conversations here I propose that we simply how configuration is passed to the preset, perhaps based on the proposal here.

@jbottigliero @Xiphe would you be willing to work with me in this effort? I think this would potentially simplify some of the work currently taking place here -- making it more clear what configuration options are available.

This would also hopefully better document certain edge-case behavior, and how to customize CHANGELOG generation, which is a topic of interest for @JustinBeckwith and myself.

[coveralls]

Coverage decreased (-0.2%) to 91.882% when pulling c42d455 on conventionalcommits-preset into 558de53 on master.

[bcoe]

@jbottigliero @stevemao I think this is ready for some review:

• I've roughed out the conventionalcommits preset, which is a fork of the angular convention, with the ability to have configuration passed in.
• I've modified conventional-changelog to make it support chaining configuration all the way through to the presets, I think this significantly decreases the amount of redirection required to configure things.

[jbottigliero]

@bcoe – just took a look at this. The configuration PR (conventional-changelog/standard-version#278) shouldn't have to change much with this direction (mostly will just need to update tests based on the desired defaults). It then just becomes a question of whether or not we want the configuration changes to land before having a conventionalcommits preset and swapping the default configurations in standard-version.

Reviewing some of the issues in conventional-changelog/standard-version and the feedback/requests in community channels it does seem like maybe the best release plan for standard-version might be:

• 6.X.X: Keeps angular as the preset, with the addition of configuration files
• 7.X.X: Switch to conventionalcommit preset.

In most cases, it seems like folks want to make minor tweaks to angluar preset and/or just have the capability to pass along properties like host. Swapping the default preset for standard-version, even in a major version seems like something we might want to isolate.

I don't want to distract from the core conversation here, so maybe it makes sense to move to release plan task in standard-version.

Just let me know what direction you are thinking of going and I can start updating standard-version to reflect these changes!

[stevemao]

Should this also be configurable?

[bcoe]

maybe eventually? I think I'd like to implement a first pass that addresses the most common feature requests that I've seen:

• the ability to more directly control the URLs to commits, ranges, and issues in the CHANGELOG generated.
• the ability to configure which types of commits show up in the CHANGELOG.

I expect we'll want to make more options configurable as we start to work our way through existing feature requests in the backlog of issues.

[stevemao]

I'm not sure how to configure things like fix or chore. Could you give an example?

[bcoe]

In most cases, it seems like folks want to make minor tweaks to angluar preset and/or just have the capability to pass along properties like host

☝️ this is exactly the types of configuration I'd like to make easier to control in the new conventionalcommits preset:

1. making it so you can easily configure which types of commits show up in the CHANGELOG.
2. making it so you can configure variables like host and issue-url, so that we can better support BitBucket, gitlab, etc.
3. allowing people to swap in alternative templates.

Well I agree that this should be a major release, I'm not convinced that there's much value in releasing a configurable version of 6.x exposing the old configuration options -- to be completely honest, I find the dials and knobs currently exposed for configuring conventional-commits very confusing (separate configuration for each module, separate writer config, parser config, and bump config); it feels like a leaky abstraction about the internals of conventional-commits.

I think the document here is a better layer of abstraction, we can continue to extend on this exposing more dials ...

---

Note: right now it's feeling like conventional-changelog-conventionalcommits will have feature parity with the conventional-changelog-angular (which doesn't currently match the actual angular conventions, which have tightened up a bit). Long story short, I don't think that the swap will be too disruptive to folks, and will make your work around exposing and documenting configuration more valuable.

[hutson]

What is our stance on releasing on every change? (I maintain my own personal changelog preset solely for the purpose of only recommending a release on fixes, features, and breaking changes.)

[bcoe]

I would like to continue releasing changes for every commit type; this is how the angular preset approaches things, and is what I myself (and I expect other users of standard-version) have come to expect.

[bcoe]

I suppose we could open this up to being configured? it feels really weird to me though as a library maintainer. If I've performed a maintenance task, such as upgrading libraries, or performance refactoring, etc., I still often want to release a patch release of my module -- I have never personally found myself in a position where the default behavior of bumping the PATCH wasn't the behavior I wanted.

[hutson]

I suppose we could open this up to being configured?

As a first pass, let's please not let my comment hold up your PR. 😅

Long-term, yes, I would really like to make releases configurable. My own preset was actually a pre-cursor to the one I wrote for my company because the number of releases for tasks, such as chores related to project configuration, refactors related to reducing technical debt, and docs related to inline comments, were becoming disruptive to our library consumers 😞 (new releases caused our dependency update tool to roll that out to hundreds of applications in near real-time, which caused lots of notifications, CI job queues to grow, etc.).

If I've performed a maintenance task, such as upgrading libraries, or performance refactoring

Those sound like tasks that effect downstream consumers. Those, in my opinion, should be released. 👍

[bcoe]

I understand this use-case better now; let's take the conversation to another issue?

[hutson]

I believe this is redundant. conventional-changelog-core currently merges the options from, say, parserOpts, over the options.config.parserOpts object. Same with gitRawCommitOpts and writerOpts.

If you don't like the preset options, you can override them by settings the appropriate options in parserOpts, etc.

[bcoe]

I honestly find this approach to configuring things very convoluted, it was @stevemao's recommendation that we start passing configuration directly into presets, and I think this is much less confusing to an implementor.

[bcoe]

also, I think the configuration is at the wrong level of granularity; as evidenced by the variety of open issues on standard-version (which is the project I work with most directly) users want to be able to:

• have more control over the URL format output in CHANGELOGs.
• have more control over which specific types of commits show up in the CHANGELOG (feat, vs, chore, etc).

The existing configuration exposes a ton of nuts and bolts about what's happening in conventional-commits several layers of abstraction away from the presets. As an example, even though you could potentially overwrite the entire writeOpts config, there's no easy way prior to this change to pass configuration to this method in the angular preset, which actually configures which items are toggled oin and off in the CHANGELOG.

[bcoe]

@stevemao is there a better way to pass configuration all the way through to the preset? without introducing this refactor -- I want the preset to have access to configuration like you suggested, but I think it should be the responsibility of upstream libraries like standard-version to accept this configuration (either from command line arguments or loading it from disk).

Long story short, the least breaking way I could think of to chain configuration all the way to the preset was to override the behavior such that presets can optionally return a factory that accepts configuration, rather than a promise.

[hutson]

The existing configuration exposes a ton of nuts and bolts about what's happening in conventional-commits several layers of abstraction away from the presets.

Thank you for the explanation @bcoe. 👍 It's a sentiment I share as well. 😅

[demisx]

Is there an example on how to make angular preset print each commit type in the change log? Or do I still have to implement a workaround like this? My apologies, but I am somewhat confused. This PR is merged, but the master still prints only 3 types be default - feat, fix and perf.

[bcoe]

@stevemao please see my most recent push, I hadn't actually exposed any configuration yet; had been working on things this afternoon.

[jbottigliero]

I find the dials and knobs currently exposed for configuring conventional-commits very confusing (separate configuration for each module, separate writer config, parser config, and bump config); it feels like a leaky abstraction about the internals of conventional-commits.

I absolutely agree with this. I wanted to make sure I understood the structure you were proposing before I start any work... I've opened #422 with two example fixtures. From the standard-version perspective it seems like, after this move, we'll only need to remove flags and clean up some of the configuration behavior (allowing the underlying packages to rely on the specified configuration files directly).

[Xiphe]

Hey, im humbled for @mention 😻. I have not worked at this topic for a long time and currently am chasing other projects. So I will not be able to contribute, sorry.

[bcoe]

@stevemao @hutson I'd be pretty comfortable landing this as a first pass at making a more configurable preset, and then iterating from there -- unless you have potentially a better idea for chaining config to the preset @stevemao? other than introducing a factory pattern.

[stevemao]

Thanks @bcoe, only thing is I'd like to see preset gone and only use config. Other than that I don't have interesting idea.

[bcoe]

@stevemao do you mean simplify this logic:

      if (typeof options.preset === 'object' && options.preset.name) {
        // Rather than a string preset name, options.preset can be an object
        // with a "name" key indicating the preset to load; additinoal key/value
        // pairs are assumed to be configuration for the preset. See the documentation
        // for a given preset for configuration available.
        presetConfig = options.preset
        options.config = conventionalChangelogPresetLoader(options.preset.name.toLowerCase())
      } else {
        options.config = conventionalChangelogPresetLoader(options.preset.toLowerCase())
      }

such that if config is an object, we assume it will be passed to the preset? I don't love the idea of getting rid of support for preset being a string value, because it would be a significant breaking change, and would require updating all existing presets.

[stevemao]

Please see #426 for the idea of removing presets

[stevemao]

Thanks for adding this!

[hutson]

Looks good to me!

[vsetka]

When will a new version (with this change) be published? I don't see any milestones.