scottrobbins/changes

A utility and framework for tracking metadata around changes made to code, generating Changelogs and other documents from those entries.

changes's Issues

All printing should to go stderr

There are points where I print to the console so that I can read input from the user. This printing should go to stderr so that the result can be piped into future commands.

Also, I assume it does but I'm interested to make sure that if i have interactive input the result can be piped to future commands.

reference: https://clig.dev/#the-basics

Review possible files errors and provide helpful output for common errors

For places where Files can't write to a file, or read a file that should be there. Instead of just throwing up whatever error message Files gives, we should look for those places and give a helpful error message.

reference:

• https://clig.dev/#errors

Add section to README explaining why I made this tool

There are other Changelog automation techniques, and most people probably don't automate their Changelog, so writing up a small section on why this tool exists would be useful.

I think I'm going to in the future write a longer blog post on this, but having something more compact in the repo would be useful

Think of a better name

"ChangelogManager" isn't ideal for the name because the intent is that it will be able to be used for much more than managing a single Changelog.

Also typing Changelog-manager in the command line is super annoying. Something that's just one word would be nice for a tool that will be frequently used.

Allow user to pass config file location as a command line argument

This is useful sometimes to be able to do.

It should still run assuming the source files are where it's called from.

Use swiftenv for macOS github workflow

Right now I include the latest version of xcode just to have swift installed. I should just use swiftenv for this because that's what I use locally.

Allow multiline messages in change entry

Because one of the goals is to allow for more flexible CI automation, we may want entries to be multiline and accept a variety of characters. An example of where this might be useful is putting example code in github releases https://github.com/vapor/fluent-kit/releases/tag/1.4.0

How do we handle multiple release builds and versions in the same repo?

There are cases where you might have a monorepo that creates multiple distribution builds. They might not all share the same version numbers either.

How can this tool support this flow easily?

Name changes files by id and add id field

I think that it'd make automation easier if the file name was some sort of an id that I could then query for that entry based on that id later. I'm thinking of using this for cases where I want to use git diffs to find what changes entries were added in a pull request and using that to then find information about what was in that entry.

Also these files are not really anything I expect anyone to read and I don't feel like losing the friendly file name is an issue. I'd like to name the file name just the id so that to find that entry by id I don't need to read the json of every single file.

Convert from YAML to JSON

Right now I use YAML for everything. While this works great, I think I should consider using JSON instead (at least for the generated files).

This should make it easier for other scripts outside of this tool to modify files if that's ever needed.

Add automation to this repo

This utility has much more functionality than just generating a Changelog, on purpose to aid in automation. I should add some of that to demonstrate its uses, as well as just for the maintainability of this repo..

This may include:

• Automating running of tests, linting, swift-format and validating a Changelog has been entered
• Automate publishing of releases both to GitHub here, Homebrew, Nix, and something like apt (if I support it, still haven't figured out the linux situation)

Should this library allow tracing?

https://github.com/apple/swift-distributed-tracing

This may not be useful for this library. But I'm trying to get a better understanding of what a "good" swift library does to fit in with the larger ecosystem.

Display query output in human readable format

I can likely display query results in a more terse or easy-to-read format other than JSON. It would be nice if I could allow this and allow them to pass a --format json or --format console or --format plain [1] if necessary.

references:

• [1] https://clig.dev/#output

Create GitHub action(s)

There's at least one GitHub action I'd like to create, which should be creating releases.

But, I want to consider any other actions that might be useful. I imagine these will come up when I'm adding CI for this repo.

Make changelog entry file name more human readable

Right now I just generate a UUID for the file name of each entry. That's fine, it doesn't use the name for anything, but I think I should make an attempt to make it more human readable.

My thinking is something like: <date>-<description>-<hash>, where the date is the iso8601 date string, the description maybe takes the first 3 or 4 words of it and hyphenates between them, and the hash just ensures the file names will be unique.

For an entry with the description Adds human readable name to changelog entry filenames. The filename might look like:

2020-05-21-adds-human-readable-name-jasdfij092390.yml

Automate linux docker image names

I now have it set up so that macOS should use swiftenv to automatically get its swift version from swiftenv. On linux I use different docker images, however. These are right now hardcoded in the GitHub ci workflow like swift:5.3.1-xenial.

These have a naming pattern and I think I can automate it so that it uses the .swift-version file to determine the docker image names so that I don't have to update the CI workflow when I update swift versions.

Benchmark / Performance test

There are a couple concerns I have:

• Given a really large # of Changelog entries (imagine it's years from now and a large team has been using this on a project for that time), does the tool still work in a sufficiently short amount of time. This is a concern because I create a different yaml file for every entry, so because it regenerates the whole Changelog entry every time, it has to read all of those. I think this should still be pretty okay, I did a quick benchmark before with 50,000 entries and optimized that by reading and parsing files concurrently. I could potentially make that even faster, but want to know if it's worth it or if I need to make adjustments to how the files are stored and read.
• Want to know how much disk space is taken up by these entries.
• Want to validate too much memory isn't taken up by reading all of these into memory (Idk what my goal for this should be)

Add ability to generate Changelog

Right now the add command will place yaml flies in the correct folders. Need to be able to generate the Changelog file(s) from these.

Because my current strategy will be to regenerate the Changelog every time instead of just appending to the current one, I want to test the performance of this when you start to get a large number of entries. I think I want to test a number a team could reasonably get to after years at around 5,000 entries. Then I want to try something kind of ridiculous like 50,000 entries.

Consider if this work can be parallelized across threads to speed it up if need be.

Because this is something I want to run every time you add, it needs to be pretty fast or it will feel cumbersome. The likely result of this is that I will want to append to the Changelog most of the time and give an option to regenerate the Changelog if need be.

Add documentation on the config file format

Obviously the config file format needs to be documented somewhere. Either in a README or in a website that has documentation for this tool.

swift-log integration for Framework

self explanatory

Mac App?

This may just be me wanting a reason to write a Mac app, but it may be nice to be able to have a Mac app to enter your entries with and view past ones, as well as add integration with Xcode source editor extensions (if it's possible to get user input in one). I'd also like a VSCode extension but Idk if II want to take that on.

If I made one, I'd want to be able to launch it very quickly to enter things

Config file question

Is there any type of file you’d want to define in the config other than a change log? If yes, should you be able to specify queries?

Add apiVersion to changes config and changes files

Tools like Kubernetes and helm and whatnot provide a file version in their config files. I think I should add something like that to both the changes files and the config. That way, in the future I can change the structure of them in breaking ways and have the CLI tool recognize it and possibly even migrate it for the user.

Add ability to to specify footer text for your Changelog file

Projects adopting this will likely have another Changelog file that they were using before. Allowing them to enter in some footer text to point to that for older versions would be helpful.

Allow ability to regenerate specific files

There are files you may want to set up in the configuration, but perhaps don't want to be generated every time you add/remove a change. For example, you may not want to actually keep a "changelog.md" file in your repo, but want to generate it on CI.

To make this happen, I think I should:

• add an option to specify whether to auto-regenerate changeling for a file in configuration
• Require users give each file some identifier
• changelog regenerate <identifier>

In the future, I want to be able to generate different types of files (for example, a json file describing changes), but that's not part of this issue

Figure out how/if automated release version number automation fits in

1.0 should give all of the tools to set up a process to automate creating a release version yourself based on the changes in this release. However, it would be useful for a CI process to be able to say "create a new release" and the tool knows the last release was 1.0.1 and you have a minor change and a patch change in there so it creates a release as 1.1.0 and returns to you the version it created.

I just don't know if this is making the tool too opinionated about your development and release flow to be useful or worth making part of the tool. You would need to make things like the Major, Minor and Patch tags some kind of special "blessed" tags to even gather this information.

Build changelog with Stencil

People may want different information in their generated chamgelog entries. For example: a link to an issue.

We should allow people to make their own Changelog format by having users build template files.

This would also let people do things like generate more types of files based on this information. I'd like to do this to perhaps regenerate READMEs.

Note: I'm not really confident this tool should get too much into making highly configurable generated files. Or if it should instead just provide hooks to call scripts in thgrvreadme that can do what they want. Perhaps then I could take the CHANGELOG generation out of this tool and leave it to a stencil script or something like that? But maybe that's be annoying for the common case. Idk I'm rambling. If it's just a link to an issue that's desired in changelog entries, maybe I just want to account for that in the tool.

Allow adding multiple tags to a single changelog entry

It's possible you want something to be added in multiple categories. I think this can still be represented by multiple yml files though.

Add ability to create release

There should be a command to create a release. When it is called it should allow the user to give the release version (validate it's a valid version code, split off the "v" if passed in). It should then create a folder under releases/, move the yaml files from unreleased to there and regenerate the Changelog

Consider building a static binary

https://forums.swift.org/t/static-linking-on-linux-in-swift-5-3-1/41989

I need to look more into this, but if it would make it easier to use the utility on systems without swift installed that's be helpful.

It would increase binary size so I'd want it to be optional.

Add ability to create releases

This should:

• Let you tell it the version number for the release
• Move all of the files in the Unreleased section to the releases section
• Collect any other useful information relating to a release you might want (need to think about what this would be
• Regenerate Changelog(s)

Polish help commands

A lot of my help descriptions were hastily added. The descriptions of the commands are partially incorrect and likely not clear.

Other things I may want to do:

• Example invocations (give people a place to start).
• May also want to suggest other commands to pipe to, such as piping JSON output to jq.
• Will swfit-argument-parser let me customize what is shown when you pass the command w/o the "--help" flag? As in, just $ changes to give informational text [1].
• Make a wiki documentation for this tool, and link to it in the utility [1]. This documentation can have many more examples.
• Look for common ways someone might use the tool incorrectly, and provide better error messages for that (this may not be immediately noticeable yet). May even want to make this a discussion topic for any future users of the CLI tool to add things they commonly mess up)

references:

• [1] https://clig.dev/#help
• https://github.com/apple/swift-argument-parser/blob/main/Documentation/04%20Customizing%20Help.md

Add support for package managers

I know I want to at least support Homebrew. I potentially also want to support Apt and Nix, not sure what's involved in that. Also Idk what I need to set up to actually test support for those.

How to avoid interactive mode on CI

The CLI has interactive modes which will ask users for missing information.

However, when you're building your CI if you are missing information you just want the command to fail. You don't want it hanging waiting for input that will never come.

Need to figure out the best way to avoid this issue without adding too much burden on the developer.

Should releases be a part of this project?

I keep thinking about how to create automatic versioning and make it work in a CI/CD system well. I keep coming back to the fact that I track what changes are a part of specific versions.

Automatically versioning would require some CI system to make commits and merge in git. This isn't impossible but always seems like friction that I wonder if it's possible to avoid somehow.

Build README with stencil

I'd like to be able to have my release CI to be able to update my README for me. Things I'd like automatically updated in changelog:

• Installation steps that include correct library / CLI versions
• Installation steps that specify the correct Swift version. (needed for installation steps)

Things that might be cool:

• README examples to have version numbers specified from this repo be automatically updated to be more recent.
  • Idk if this would be useful enough to warrant the complexity, but it would be kind of neat if you could run all of those queries / commands in the README against this repo to see the result.

Upgrade to Swift 5.5 & Async/Await

In reality, Async/Await + actors will only help with the querying code of this CLI utility. But for fun I'd like to try it out and see how it affects performance.

Performance may be different depending on macOS version as Monterrey has the cooperative thread pool built in.

Add ability to check if Changelog entry has been added in a PR

This would be really great for CI systems to check if there's a Changelog entry in this PR.

The only thing I'm not sure about is how much I want to tie this tool to git. Thus far, it purposefully isn't reliant on it, or git commits. Making this separation means I don't have to worry about different people's development flows with git and if this tool is satisfying all of them.

Add ability to specify header text

I added the ability to change the footer text on your generated files. I would also like to be able to change the header text.

Files can be generated for various reasons, and the current header text strongly implies its for a change log

Output on success for non-query commands

the correct output for a query are the results of the query. however, things that would otherwise just not have output should still give some confirmation that it completed successfully, otherwise people will immediately follow the tool with a $ git status or something like that to know their command happened successfully.

May want to consider adding a --quiet flag for shell scripts if it will add unwanted noise.

references:

• https://clig.dev/#output

Relocate config file?

It's kind of a standard, and kind of an annoying one to put your config file in the top level of a project. I'm wondering if I should follow the XDG spec-like thing [1] where I default for the config file to be in .config/changes.yml and the working directory is one up from that?

references:

• [1] https://clig.dev/#configuration

Create framework

Right now it's just a CLI tool, but I want to be able to use it from Swift scripts, so next to the executable I should have a framework that you can call into

Allow custom metadata

I think it would be cool to be able to add custom metadata to your entries and then be able to get that information using the queries feature.

For example, some teams may want to always have a url or story # for their issue tracker. Others may want to be able to add an Author to all of them, perhaps add a much longer description, etc

Add ability to query Changs by id

I added an id concept my changes. Now I'd like for you to be able to query by id in the CLI

Put queries under `query` subcommand

Right now you have things like changes entries and changes releases. I think it will make the commands more self explanatory to read later if they're in a script. It also opens the door for a changes query --help command that can give an overview of the options. It will also clean up the top level help text by breaking the related things (querying) out of that list.

Old:

$ changes releases --start 0.1.0
$ changes entries --tags Added Changed

New:

$ changes query releases --start 0.1.0
$ changes query entries --tags Added Changed
$ changes query --help # Would list all of the things that could be queried

Create some way to add files with changes

There are times that I may want to associate files with my changes.

For example, in my GitHub releases I may want to add markdown with the example. I could add this as metadata to the changes, but I'd lose the ability to edit it with highlighting like I would if I made a file with the .md extension and then somehow associated it with the change. Similarly, I may want images associated with this change to add to the release in GitHub.

It'd be nice if these were stored along with the changes so that users didn't have to come up with their own schema for where to put them and manage it all themselves.

Add ability to query information for arbitrary categories and releases

I want to be able to print in the console neatly, print in the console as json (so jq can parse) and output arbitrary queries to a file.

I want there to be the ability to have categories defined not associated to a file, and to make a query saying to get results for all entries in 1 or more categories, and possibly let you specify from what release(s) you would like this from.

One of the reasons for this is being able to make something parsable to use for release notes either for automating GitHub releases, slack notifications or release notes on app stores.

Another reason is as a debugging tool to be able to say "What are the Changelog entries between X release and Y release?".