specify the config format that conventional-changelog exposes

[bcoe]

Background

Hey 👋 @jbottigliero, @hutson, @stevemao

I've created this repo for specifying our config format. I picked up this approach of splitting out specifying schemas in their own repos from @ahmadnassri. Here's a great example of the approach in action:

https://github.com/ahmadnassri/har-spec

@ahmadnassri mentioned to me there might even be a library he can open-source that automates the README generation, this would be slick.

First Pass

So far these are the variables I've thought to expose:

types

An object representing the explicitly supported commit message types, and whether they should show up in generated CHANGELOGs.

{ type: 'feat', name: 'Features' },
    { type: 'fix', name: 'Bug Fixes' },
    { type: 'perf', name: 'Performance Improvements' },
    { type: 'revert', name: 'Reverts' },
    { type: 'docs', name: 'Documentation', hide: true },
    { type: 'style', name: 'Styles', hide: true },
    { type: 'chore', name: 'Miscellaneous Chores', hide: true },
    { type: 'refactor', name: 'Code Refactoring', hide: true },
    { type: 'test', name: 'Tests', hide: true },
    { type: 'build', name: 'Build System', hide: true },
    { type: 'ci', name: 'Continuous Integration', hide: true }

issueUrlFormat

A string representing the issue URL format (allowing a different URL format to be swapped in for Gitlab, Bitbucket, etc):

'{{host}}/{{owner}}/{{repository}}/issues/{{id}}'

commitUrlFormat

A string representing the URL of a specific commit at a hash.

'{{host}}/{{owner}}/{{repository}}/commit/{{hash}}'

compareUrlFormat

A URL representing the comparison between two git shas.

'{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}'

[bcoe]

@hutson @stevemao any objection to adding @jbottigliero to the organization, so that he can potentially help flesh this out further?

[stevemao]

Please just add anyone to the org if they want to contribute :)

[jbottigliero]

Thanks for the invite - looking forward to contributing and working with you all on this!

How much customization do we want to allow in the actual layout of the CHANGELOG.md? Based on the initial types proposal, I assume the name becomes the section headings. Do you think it's worthwhile exposing some way to group individual types into a single heading?

Example:

  types: [
    { type: 'feat', name: 'Features', section: 'Updates'},
    { type: 'fix', name: 'Bug Fixes', section: 'Updates'},
    { type: 'test', name: 'Tests', section: 'Internal'},
    { type: 'build', name: 'Build System', section: 'Internal'},
    { type: 'ci', name: 'Continuous Integration', section: 'Internal'}
  ]

Alternativly, does it make sense to remove the requirement of name altogehter and only associate the types with sections? name could also be used in a similar way, section just seems more in line with how it will appear in the CHANGELOG.md (FWIW, I can also see value in being able to specify both in order to categorize/format within a section).

  types: [
    { type: 'feat', section: 'Updates'},
    { type: 'fix', section: 'Updates'},
    { type: 'test', section: 'Internal'},
    { type: 'build', section: 'Internal'},
    { type: 'ci', section: 'Internal'}
  ]

To give a real-world example, I'm working with a current extension of the Angular preset that will account for both improvement: and the short-hand imp:. We want these both to show up under the "Improvements" section of the CHANGELOG.md and we currently do this by specifying writerOpts.transform

---

edit: removed the hide attributes from the examples (not necessary).

[bcoe]

@jbottigliero right now, once renamed, commits are grouped together; so if feat and ci both remapped to the name Features, they would be grouped together.

... I kind of like the idea of renaming name to section.

[jbottigliero]

It doesn't look I have push access to this repository, or maybe it's just due to there not being a trunk, yet...

BUT, I went ahead and started to translate the above to a format similar to the har-spec, here. I'll need to update a few links once it's actually in the repository, but figured it might help with referencing more specific changes.

Looking at type it seems like sectionor hidden (I did change this to an adjective) should need to be required. In the absence of both it almost seems like it should take on the behavior of hidden rather than having a default section for types... but maybe we avoid that confusion by stating it must contain one or the other.

standard-version appers to inject a header; Seems like that could be covered by a top-level title attribute.

There are a few options in the writer we might want to move over (reverse, all the templates and partials, maybe some of the other sorting options, etc.). However, I do worry by just duplicating them here, it might not result in the clarity we're striving toward...

[cristovaov]

Hi there, sorry to barge in like that. I've only recently started using standard-version and It's a feature I'd like to see land. Are you open to my user perspective on it and where would it be best to submit it (in this thread or separate issue)? Cheers.

[bcoe]

@jbottigliero you should have access now.

[bcoe]

@cristovaov very open to user perspective; the hope is to define some really easy to configure dials and knobs that don't expose too many of the inner workings of conventional-changelog core.

@jbottigliero perhaps let's worry about the header standard-version injects in latter work; my concern is that if someone changes the header we don't have a great approach for not breaking someone's CHANGELOG -- tldr; I don't think we need to address that issue in this first pass?

[jbottigliero]

I've opened a PR with the proposed changes thus far, and some copy to cover substitutions and explanations of the various properties (https://github.com/conventional-changelog/conventional-changelog-config-spec/pull/2).

@bcoe makes sense, skipping a title field for now sounds good to me.

[bcoe]

@jbottigliero I think you've got this to a great starting point.