Configuration Format Overhaul

[miniscruff]

Discussed in #610

^{Originally posted by miniscruff March 3, 2024}
Currently there is a bit of inconsistency in whats supported as well as a few overloaded terms, like header and format, that I really want to clean up. Additionally with the addition of projects and monorepo support, the configuration file has gotten quite big.

It was always part of the design of changie to support a wide range of projects, formats, inputs, outputs and so on, so this is not unexpected really. But, I think we can do better on making the config format more clear.

Some notes so far:

• Use Markdown link references #602 would require changelog level footers, it would also make sense to provide the header equivalent.
• Leveraging changie for ADRs (architectural decision records) #600 has some alternative uses that may be possible to support as well
• there has been a lot of suggestions or issues related to dependabot/renovate bot and how changie may or may not be able to include these updates automatically, I am not quite sold on this but something to consider.

One thing to note is that, any existing functionality will remain as is, really what I want to do is clean up some wording and organization of the config file.

To give an example there are 3 config values that look like they are editing the same thing, but in practice are not really.

1. versionFooterPath
2. versionFormat
3. versionHeaderPath

Version footer path and header path are file paths for per version headers and footers, as in the generated release notes file. While the version format is the line in that file that relates to the version.

This discussion will be my note taking space until it feels more stable, for now know that existing configs will work and remain working until, if ever, a changie v2 is required. I will definitely find a way to make sure renamed/moved configs are properly documented as well.

Design

Changie works in multiple steps:

• Prompt users for an update, producing a changie fragment
• Batching unreleased changie fragments into a brand new release note
• Merging release notes into a changelog

Changie aims to allow you to configure every aspect of all steps.
Additionally, for configurations that are similar/shared between both steps
we try and be consistent.
For example: header and footer configs match between release note files and changelog files except for the data that is passed to the templating.

Shared types

newline_type:
    before: 0 # amount of newlines to add before writing text
    after: 1 # amount of newlines to add after writing text

line_prompt_type:
    key: key of our prompt output used in file/fragment templates
    label: display label when rendering prompts ( defaults to key if empty )
    line format: line format of our component ( defaults to line format of all components )
        ??? can projects have line formats? What would that do?

file_writer_type:
( custom type for what data to pass to template cache, we need to document )
    file path: file path + template cache to generate text
    line format: string + template cache to generate text
    newlines: see newline_type

Full Config

rootDir: .changes ( from ChangesDir )
env prefix: CHANGIE_ ( unchanged )
fragment:
    dir: directory for unrelease fragments relative to root dir ( from UnreleasedDir )
    file format: template format for generating the file name of fragments ( from FragmentFileFormat )
    posts: post processing ( from root posts )
    prompts: ( from Customs )
project:
    version separator: ( from project version separator )
    options: ( from Projects )
        - key: key of our component used in file/fragment outputs
          label: output label when selecting in prompts ( defaults to key if empty )
          ( maybe inline file_writer_type if projects have a use for line_prompt_type )
          replacements: ( unchanged )
          changelog: ( matches the root changelog config and will merge the root with each project )
component:
    line format: output format of our component line, can be empty
    newlines: see newline_type
    options:
    - line_prompt_type ( inline these values )
      post: post process options ( just like kind config, ran before kinds if both configured )
kind:
    line format: output format of our kind line, required
    newlines: see type
    options:
        - line_prompt_type ( inline these values )
          change format: per kind option of the change format ( takes precedence over default change line format )
          post: post process options (unchanged kind config)
          auto level: unchanged
          skip: ( extra level needed? )
            body: unchanged
            default prompts: unchanged
            default post: unchanged
          ??? prompts: ( from additional choices )
          ??? should this be wrapped in a prompts and have skip global under it?
change: ( renamed from body? )
    line_prompt_type ( inline these values ) ( default to body )
    min_length: min length validation
    max_length: max length validation
    skip: true/false
    newlines: see type
releaseNotes:
    extension: File extension for release notes ( from VersionExt )
    version: see file_writer_type
    header: see file_writer_type
    footer: see file_writer_type
    newlines: see newline_type
changelog: ( shared type between root and project.options[*].changelog )
    output: output path to changelog file ( from ChangelogPath )
    header: see file_writer_type
    footer: see file_writer_type
    newlines: see newline_type
    replacements: moved to better support projects

Release note file format:

<header file path>
<header line format>

<version line format>
<for each component if enabled>
    <for each kind if enabled>
        <for each change>
            <change line format>
        <end change>
    <end kind>
<end component>

<footer line format ( FooterFormat )>
<footer file path>

Changelog format:

<header file path>
<header line format>

<for each release note>
    <release note file>
<end release note>

<footer line format>
<footer file path>

Changie's changie config under new format

rootDir: .changes
fragment:
  dir: unreleased
  prompts:
    - key: Issue
      type: int
      minInt: 1
changelog:
  output: CHANGELOG.md
  newlines:
  header:
    filePath: header.tpl.md
    newlines:
      after: 1
  replacements:
    - path: 'docs/config.toml'
      find: "  version = '.*"
      replace: "  version = '{{.Version}}'"
    - path: 'docs/static/version.json'
      find: '    "latest": ".*"'
      replace: '    "latest": "{{.Version}}"'
    - path: package.json
      find: '  "version": ".*",'
      replace: '  "version": "{{.VersionNoPrefix}}",'
releaseNote:
  extension: md
  version:
    lineFormat: '## {{.Version}} on {{.Time.Format "2006-01-02"}}'
kind:
  lineFormat: '### {{.Kind}}'
  newlines:
    before: 1
    after: 1
  options:
    - label: Added
      auto: minor
    - label: Changed
      auto: major
    - label: Deprecated
      auto: minor
    - label: Removed
      auto: major
    - label: Fixed
      auto: patch
    - label: Security
      auto: patch
change:
  lineFormat: '* [#{{.Custom.Issue}}](https://github.com/miniscruff/changie/issues/{{.Custom.Issue}}) {{.Body}}'
  newlines:
    after: 1

Current Notes:

1. The use of skip vs enabled. Skip is like a negative not a positive value of what we are doing
2. Migration plan: Do we mark all existing config options as optional pointers without defaults?