Leveraging changie for ADRs (architectural decision records)

[sheldonhull]

I was considering a few alternative uses of changie and thought I'd share the idea in case it sparks some ideas.

I've been using for my personal accomplishments tracking at work, and also considered using for team/repo architectural decision records.

The workflow of changie helps solve a lot of the issues/conflicts you can run into when using normal markdown incremental versions.

I think a few things would let changie be used for these additional purposes without compromising the unique focus of changie.

A few ideas

• ability to generate a markdown style table summary of all the changes at the top of the "changelog/adr page". I could figure this out with some good templating at the top most likely.
• the yaml output isn't multiline output. This makes code review of the content tricky. I can't easily support reading & reviewing the content like I could with using markdown and semantic sentences (each sentence is on its own line).
• Yaml output can't apply markdown formatting so it commonly changes.
• Partially solved. ADRs require a status field so a custom field in changie works fine for this as long as approval is essentially just the pull request itself.

I think a few sections for contributing changie template examples and scripts could be useful for sharing these alternative ways to use.

[miniscruff]

Hey @sheldonhull every so often I look at this post and try to consider what this may mean for changie. I did finally decide to google ADR this time and that helped. My understanding could be off here but let me describe how I would go about this.

First, an ADR to me probably also comes with the assumption we have some sort of architectural documentation such as some diagrams, charts, etc. Maybe something like mermaidjs or draw.io stuff. An ADR would accompany any changes we make to the existing design, thus we can conclude a PR that changes the design would then require a changie fragment. Additionally, given the system I would probably use something like calver rather then semver. But that is a minor point.

A changie config I would try given my understanding of ADR's:
( Note that I didn't actually try this so its probably going to have a few issues... )

versionFormat: '## {{.Version}}' # verison would be calver, so no date needed
# it is also assumed you would create a new version for each change as its a big deal?
changeFormat: > # whatever yaml rule here combines newlines...
  In the context of [#{{.Custom.Issue}}](https://github.com/proj/repo/issues/{{.Custom.Issue}}),
  facing {{.Custom.Concern}}
  we decided for {{.Custom.Option}}
  to achieve {{.Custom.Quality}}{{if .Custom.Downsides }},accepting {{.Custom.Downsides}}{{end}}.
kinds:
  # skip body option is not possible without a custom
  # kind config and I just realized that...
  - label: Ignore me
    skipBody: true
custom:
- key: Issue
  type: int
  minInt: 1
- key: Concern
  type: string
  minLength: 5
- key: Option
  type: string
  minLength: 5
- key: Quality
  type: string
  minLength: 5
- key: Downsides
  type: string
  minLength: 5
  optional: true

Just some initial thoughts.

[sheldonhull]

Ok, so normally you'll want to edit outside changie, but I get why you'd use the template above in the context of changie.

I think a larger body is typical and not phrases.

The biggest issue is that you really need each file to be more calver-kebab-title.md in the result and the compilation of a changelog is actually less important.

Now that I think about it, the only way I see changie working on those areas is actually more of a fork of changie's concept instead. I think this probably should be closed as the use case is similar in fragment files, but the editing, workflow, etc is probably not the right fit.

[miniscruff]

Well template aside, you can easily build calver releases using changie batch, it's what I do at work now. If you don't need the changelog you can just ignore changie merge that's no problem. I wouldn't use the fragments I would still run batch.

But yea I have not used adr before but I am definitely going to consider trying something for our iac work and will let you know if changie can be useful. Might just need some more aggressive ci/CD scripts.