config v2 #847

miniscruff · 2025-12-28T08:46:45Z

Closes #848

Check the following

Maintain high code coverage
Be properly formatted
Documentation changes are included
Include a change file if expected

thompson-tomo

I like the direction this would be taking us, and on thinking about it during my review i think we would be better suited to further reduce the top level config options as proposed in #847 (comment)

With my prefered document approach we would have

document:
  - key: changelog
    mode: append
    header:
      newlines:
        after: 1
  - key: news
    mode: standalone
    header:
      newlines:
        after: 1
...
project:
  - key: project-A
    documents:
      - changelog
  - key: project-B
    documents:
      - news
      - changelog
  - key: project-C
    documents:
      - news

This config approach would mean that we could have a different combination of docs per project, by default all document templates are used unless it is set.

thompson-tomo · 2025-12-29T03:09:40Z

cmd/batch.go

 		b.VersionHeaderPath,
 		b.OldHeaderPath,
-		b.config.VersionHeaderPath,
+		b.cfg.ReleaseNotes.Header.FilePath,


shouldn't this be

Suggested change

b.cfg.ReleaseNotes.Header.FilePath,

b.cfg.ReleaseNotes.Version.FilePath,

probably, will take a look

thompson-tomo · 2025-12-29T03:18:24Z

cmd/batch.go


-	_ = core.WriteNewlines(b.writer, b.config.Newlines.EndOfVersion)
-	_ = core.WriteNewlines(b.writer, b.config.Newlines.AfterReleaseNotes)
+	_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Version.Newlines.After)


This setting was already used and section makes it conceptually clearer.

Suggested change

_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Version.Newlines.After)

_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Section.Newlines.After)

thompson-tomo · 2025-12-29T03:19:11Z

cmd/batch.go

-	_ = core.WriteNewlines(b.writer, b.config.Newlines.EndOfVersion)
-	_ = core.WriteNewlines(b.writer, b.config.Newlines.AfterReleaseNotes)
+	_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Version.Newlines.After)
+	_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Newlines.After)


Suggested change

_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Newlines.After)

_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Chapter.Newlines.After)

thompson-tomo · 2025-12-29T03:30:11Z

cmd/latest.go


 		l.Project = pc.Key
-		projPrefix = pc.Key + config.ProjectsVersionSeparator
+		projPrefix = pc.Key + cfg.Project.VersionSeparator


Suggested change

projPrefix = pc.Key + cfg.Project.VersionSeparator

projPrefix = pc.Key + cfg.Project.Version.Separator

thompson-tomo · 2025-12-29T03:45:59Z

cmd/diff.go

 		for i := range min(int(versionCount), len(vers)) {
 			if !firstOutput {
-				err := core.WriteNewlines(writer, config.Newlines.AfterChangelogVersion)
+				err := core.WriteNewlines(writer, cfg.Changelog.Newlines.After)


This naming feels out of place should we reuse

Suggested change

err := core.WriteNewlines(writer, cfg.Changelog.Newlines.After)

err := core.WriteNewlines(writer, cfg.ReleaseNotes.Section.Newlines.After)

thompson-tomo · 2025-12-29T03:55:28Z

cmd/merge.go

+	if cfg.Changelog.Header.FilePath != "" {
+		err = core.AppendFile(writer, filepath.Join(cfg.RootDir, cfg.Changelog.Header.FilePath))


Increase consistency

Suggested change

if cfg.Changelog.Header.FilePath != "" {

err = core.AppendFile(writer, filepath.Join(cfg.RootDir, cfg.Changelog.Header.FilePath))

if cfg.ReleaseNotes.Title.FilePath != "" {

err = core.AppendFile(writer, filepath.Join(cfg.RootDir, cfg.ReleaseNotes.Title.FilePath))

thompson-tomo · 2025-12-29T03:55:59Z

cmd/merge.go

 		}

-		_ = core.WriteNewlines(writer, cfg.Newlines.AfterChangelogHeader)
+		_ = core.WriteNewlines(writer, cfg.Changelog.Header.Newlines.After)


Suggested change

_ = core.WriteNewlines(writer, cfg.Changelog.Header.Newlines.After)

_ = core.WriteNewlines(writer, cfg.ReleaseNotes.Title.Newlines.After)

thompson-tomo · 2025-12-29T05:17:04Z

core/config_main.go

+	Change       ChangeConfig       `yaml:"change"`
+	ReleaseNotes ReleaseNotesConfig `yaml:"releaseNotes"`
+	Changelog    ChangelogConfig    `yaml:"changelog"`


Consolidated into 1, based on current implementation

Suggested change

Change ChangeConfig `yaml:"change"`

ReleaseNotes ReleaseNotesConfig `yaml:"releaseNotes"`

Changelog ChangelogConfig `yaml:"changelog"`

ReleaseNotes ReleaseNotesConfig `yaml:"releaseNotes"`

Or alternatively if implementation switched

Suggested change

Change ChangeConfig `yaml:"change"`

ReleaseNotes ReleaseNotesConfig `yaml:"releaseNotes"`

Changelog ChangelogConfig `yaml:"changelog"`

Changelog ChangelogConfig `yaml:"changelog"`

However my preference would be

Or alternatively if implementation switched

Suggested change

Change ChangeConfig `yaml:"change"`

ReleaseNotes ReleaseNotesConfig `yaml:"releaseNotes"`

Changelog ChangelogConfig `yaml:"changelog"`

Documents DocumentConfig[] `yaml:"document"`

I am still refining all the terms and parts of the config, it was very rough when I started the design coming up on 2 years ago. I do want to do a full pass over on the anatomy of a changelog which is where some of the terms I have been using will need to be refined a bit. Like "a change" versus the "changelog" is not the most helpful at the moment. I don't even think I have enough of the properties in yet and certainly not all the newline spots. So bare with me.

No worries. What I think would help is to document the composition of the generated output which will help to check and verify the terminology being used.

See comment on body of PR.

thompson-tomo · 2025-12-29T05:18:20Z

core/config_main.go

+	EnvPrefix string `yaml:"envPrefix,omitempty"`
+
+	// TODO: docs
+	Fragment     FragmentConfig     `yaml:"fragment"`


Could this also be added to the consolidated property.

thompson-tomo · 2025-12-29T05:20:39Z

cmd/batch.go

+			b.cfg.Change.Newlines.Before+1,
+			b.cfg.Change.Newlines.After,


Suggested change

b.cfg.Change.Newlines.Before+1,

b.cfg.Change.Newlines.After,

b.cfg.ReleaseNotes.Change.Newlines.Before+1,

b.cfg.ReleaseNotes.Change.Newlines.After,

miniscruff · 2025-12-30T08:24:40Z

Unrelated but I never expected to get any reviews so I didn't have my discord webhook enabled for PR reviews

thompson-tomo · 2025-12-30T23:54:25Z

What would be helpful is to be able to see a visual & textual representation of the composition of a document produced by changie.

My thoughts would be the following:

A document is generated by the changie merge process. The document contains a title followed by one or more chapters.
A chapter represents a component and contains atleast a heading ie name of the component followed by one or more sections
A section represents a version and contains atleast a heading ie version followed by one or more blocks of content
A block represents either an issue-kind and contains atleast a heading ie issue-kind followed by one or more fragments when generated by changie or is a user defined block similar to what we have with versionHeader etc.
A fragment represents what was changed

For simplicity purposes this solution would mean we remove the changeFormat & format option from KindConfig and instead add them to a new BlockConfig option along with a list of issue kinds to be included in that fragment. The nice thing is it would enable issue kinds to easily be grouped together into a single block, allows multiple custom fragments with the potential for blocks to be between issue kinds etc.

miniscruff · 2025-12-31T09:05:58Z

What would be helpful is to be able to see a visual & textual representation of the composition of a document produced by changie.

My thoughts would be the following:
* A `document` is generated by the changie merge process. The document contains a `title` followed by one or more `chapters`.

* A `chapter` represents a `component` and contains atleast a `heading` ie name of the `component` followed by one or more `sections`

* A `section` represents a `version` and contains atleast a `heading` ie `version` followed by one or more `blocks` of content

* A `block` represents **either** an `issue-kind` and contains atleast a `heading` ie `issue-kind` followed by one or more `fragments` when generated by changie **or** is a user defined block similar to what we have with versionHeader etc.

* A `fragment` represents what was changed
For simplicity purposes this solution would mean we remove the changeFormat & format option from KindConfig and instead add them to a new BlockConfig option along with a list of issue kinds to be included in that fragment. The nice thing is it would enable issue kinds to easily be grouped together into a single block, allows multiple custom fragments with the potential for blocks to be between issue kinds etc.

Hm, a very different set of terms, here is the layout from the original discussion I created, ignoring the header/footer stuff:

Release Notes:

<version>
<for each component if enabled>
	<component>
<end component>

<for each kind if enabled>
<kind>
<end kind>

<for each fragment file>
    <fragment>
<end fragment>

Where version, component, kind and fragment are just a format we output.
And each has a separate option for before and after newlines.

Changelog File:

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

To phrase it similar to you, the list is something along the lines of:

A changelog is generated by the changie merge command. It contains one or more release notes. It may also be split into different projects.
A project is an optional layer by splitting one changie config, and likely one repository, across many output changelogs. By in large, you are meant to configure each project identically, otherwise you might be better of just creating a different .changie.yml in each directory.
A release note is generated by the changie batch command and represents a single releasable point with a semver version. It contains one or more fragments ordered by component if configured, and by kind if configured.
A component is an optional layer of organization that allows you to split a single release note into smaller sections while only maintaining one changelog.
A kind is an optional layer for release notes that allows specifying per fragment what type of change you made. Think feature, refactoring, security and so on.
A fragment represents a single user affected change. If configured a fragment also includes a kind, component or project.

Maybe that is intuitive, not sure, it's kinda late.

thompson-tomo · 2026-01-01T00:46:56Z

So a comparison of the options would be:

option a	option b	option c
changelog	document	document
project	chapter - component	chapter - project
release note - version	section - version	section - version
component		sub-section - component
kind	block - kind	block - kind
fragment	fragment	fragment

What I had missed was multiple projects in 1 document, hence new option c.

Personally I don't like using terms like changelog/release notes to describe the parts of the file produced as for me and I am sure other people, they are different things with many differences making them alternatives and not subset. See announcekit.app, releasecat.io, changelogfy, appcues.com, releasenotes.pm etc which highlight my thinking.

In my past role for each release I was creating 3 documents each with different audiences:

changelog - support team
release notes - field engineers & customers
release news - Sales team & customers

Also by using generic terms we allow for greater reuse including adr use case etc

miniscruff · 2026-01-02T06:11:52Z

So a comparison of the options would be:
option a option b option c
changelog document document
project chapter - component chapter - project
release note - version section - version section - version
component sub-section - component
kind block - kind block - kind
fragment fragment fragment

What I had missed was multiple projects in 1 document, hence new option c.

Personally I don't like using terms like changelog/release notes to describe the parts of the file produced as for me and I am sure other people, they are different things with many differences making them alternatives and not subset. See announcekit.app, releasecat.io, changelogfy, appcues.com, releasenotes.pm etc which highlight my thinking.

In my past role for each release I was creating 3 documents each with different audiences:
* changelog - support team

* release notes - field engineers & customers

* release news - Sales team & customers
Also by using generic terms we allow for greater reuse including adr use case etc

While I appreciate the research and thought put into this. I have a few comments:

Using changelog as the final output is intentional, it is kinda where the name changie comes from.
The use of release notes as it pertains to the output of batch may not be the most accurate according to those guides, if you write technical fragments. But, I have suggested to many, and it should be somewhere in the docs, that you write fragments to be user facing, such that you could share them.
The idea of even having two steps, a batch and merge, is so that after you batch, you could manually add content separate from the fragments, such as images, overviews or calls to action.
This more or less aligns with the definition that I can read ( granted I am not feeling great so I will be re-reading them soon )
Now, your terms are quite accurate in terms of an extremely generic output documents. But, since these are just internal terms, and the output of changie is changelog specific, I prefer trying to keep it specific to changelogs.
Projects have separate changelogs, that is why you would use projects, if you want separate changelogs. If you wanted a single changelog you would use a combination of components and kinds.

miniscruff added 9 commits December 28, 2025 00:46

work in progress for a config v2

7f3642b

fixed cmd/next with new changes

bdc3a4b

fixed latest command

d5b5a20

fixed compile errors in init

78a48bf

fix compile errors in diff

15a8fdd

fix new command compile errors

94b6cb1

fix merge cmd compile issues

ebbf8c8

fixed all the batch compiler errors

dac61f0

good stopping point, getting closer

dc08b3d

This was referenced Dec 29, 2025

Allow components to be associated with projects #837

Open

Define components in external flat file #838

Open

Define projects using patterns #839

Open

thompson-tomo reviewed Dec 29, 2025

View reviewed changes

	b.cfg.ReleaseNotes.Header.FilePath,
	b.cfg.ReleaseNotes.Version.FilePath,

	_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Version.Newlines.After)
	_ = core.WriteNewlines(b.writer, b.cfg.ReleaseNotes.Section.Newlines.After)

	projPrefix = pc.Key + cfg.Project.VersionSeparator
	projPrefix = pc.Key + cfg.Project.Version.Separator

	err := core.WriteNewlines(writer, cfg.Changelog.Newlines.After)
	err := core.WriteNewlines(writer, cfg.ReleaseNotes.Section.Newlines.After)

		if cfg.Changelog.Header.FilePath != "" {
		err = core.AppendFile(writer, filepath.Join(cfg.RootDir, cfg.Changelog.Header.FilePath))

	_ = core.WriteNewlines(writer, cfg.Changelog.Header.Newlines.After)
	_ = core.WriteNewlines(writer, cfg.ReleaseNotes.Title.Newlines.After)

config v2 #847

Are you sure you want to change the base?

config v2 #847

Uh oh!

Conversation

miniscruff commented Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thompson-tomo left a comment • edited by miniscruff Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miniscruff commented Dec 30, 2025

Uh oh!

thompson-tomo commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miniscruff commented Dec 31, 2025

Uh oh!

thompson-tomo commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miniscruff commented Jan 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miniscruff commented Dec 28, 2025 •

edited

Loading

thompson-tomo left a comment •

edited by miniscruff

Loading

thompson-tomo commented Dec 30, 2025 •

edited

Loading

thompson-tomo commented Jan 1, 2026 •

edited

Loading