scottrobbins / changes Goto Github PK
View Code? Open in Web Editor NEWA utility and framework for tracking metadata around changes made to code, generating Changelogs and other documents from those entries.
License: MIT License
A utility and framework for tracking metadata around changes made to code, generating Changelogs and other documents from those entries.
License: MIT License
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
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:
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
"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.
This is useful sometimes to be able to do.
It should still run assuming the source files are where it's called from.
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.
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
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?
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.
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.
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:
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.
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:
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.
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
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.
There are a couple concerns I have:
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.
Obviously the config file format needs to be documented somewhere. Either in a README or in a website that has documentation for this tool.
self explanatory
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
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?
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.
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.
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:
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
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.
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.
It's possible you want something to be added in multiple categories. I think this can still be represented by multiple yml files though.
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
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.
This should:
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:
jq
.$ changes
to give informational text [1].references:
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.
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.
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.
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:
Things that might be cool:
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.
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.
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
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:
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:
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
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
I added an id concept my changes. Now I'd like for you to be able to query by id in the CLI
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
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.
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?".
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.