For me, I find this approach better than nothing and would not shame or discourage someone from using it over hand written.
That said, I am wanting a Github action based release workflow and want it to scale to manual edits of changelogs, so this is insufficient for me. Instead, I've been taking notes on changelog fragments as I hope they can offer the best of both worlds, see https://github.com/epage/epage.github.io/issues/23
> A plumber who works for free is a rare thing to see, however in software it seems lots of people _expect_ it to be created like that. Not uncommon at all to see comments in HN saying that "oh well if it's not OSS I won't try this software you're showing off". Try saying to a carpenter that if they don't give away their new chairs for free, you wouldn't even start to think of getting one! :)
A big difference is plumbers use interchangeable parts and you are mostly paying for their time and skill. With closed source software, you are getting a blackbox that you can't extend beyond what the creators allow and the creators will only extend so long as they are in business. After that it might still be usefull but a liability or can be useless.
I've seen guides for detecting terminal support for colors, hyperlinks, emoji, etc but not "fancy" terminal control like this. Anyone know of any? In one CLI I work on, some others are concerned about the long tail of users and wanting to make sure no one has a bad experience by default.
This isn't using any "fancy" terminal features, aside from the synchronized update sequences (which terminals that don't support typically will ignore, though windows has a special case where it must be ignored). That said, you can query the terminal for support for this sequence if you wanted to.
Other than that, it's using standard ANSI sequences: `\r` to return the cursor to the beginning of the line, `\x1bM` (Reverse Index) to move the cursor up a single line (repeated n times), and then `\x1b[J` to clear the screen below the cursor position. All of these are sequences defined at least since the VT220, probably the VT100.
> `\x1bM` (Reverse Index) to move the cursor up a single line (repeated n times), and then `\x1b[J` to clear the screen below the cursor position. All of these are sequences defined at least since the VT220, probably the VT100.
For whatever reason, the people I'm collaborating with have the impression these aren't universal enough. And of course termcaps is out of vogue.
Less is more; worse is better. I don't remember where I originally saw it, but some rules of thumb that seem to serve well are:
- information shown to the user should be able to be consumed; if it's too fast to read and not displayed in perpetuity (e.g. logged once complete) it's essentially just unnecessary movement akin to a really noisy "spinner"
- no new "movement" (e.g. spinnner/progress esque) within ~200ms will result in the user thinking something is hung
- every permanent line away from input command prompt is sacred; e.g. too much movement vertically (e.g. spamming logs) should be reserved for "verbose" output where the user explicitly asks for it. The effort by the user to scroll the buffer afterwards should be worth it.
The new zig progress IMO breaks a these rules and I'm not a huge fan of it except out of novelty in design.
Cargo's current output essentially only breaks the vertical scrolling rule; if I were BDFL I'd probably just use a single line indicatif spinner ephemerally instead of displaying all "downloading" and "compiling" lines unless someone asked for a "verbose" output and wanted to actually see those lines logged. It could be argued that using a tree of indicatif spinners for long running parallel tasks might be interesting? But determining what is "long running" would be extremely difficult to know ahead of time, and accidentally making an 8-frame spinner would just appear like useless noise. Add to that the max parallelization with Rust, especially in debug builds can be quite high which would end up looking much like the this zig output where 99% of the lines only last for a few frames.
The vertical scrolling has the advantage that when you are watching a build go, and you see a certain step's taking a long time, it doesn't ever disappear from the terminal completely. You don't need to look through dependencies some other way and figure out which matches the thing you saw, or do a clean build to see the bottleneck again, etc.
Visiting the Netherlands right now and every time I visit local.google.com, it reverts back to Dutch. I had no idea what the symbol on its own and only figured it out when searching how to get things back to English and seeing the symbol used in that specific context.
My problem with maintaining a changelog during development is it can serve as a source of merge conflicts. Instead, I follow Covnentional Commit style and manually write my changelog entries based on the commits. I have a tool [0] that can show me the relevant commits for a package in my repo and automates the entire release process, including doing sanity checks.
I also feel like releasing from CI is hard, especially if you have multiple packages in a repo [1], including
- You can't as easily introspect the process
- You can't as easily recover from failure
- Getting a lot of the nuance right, like handling releases concurrent to merging of PRs, is difficult
- When the workflow is an ever-present "release PR" that you merge when ready has issues with selecting which packages to release and at what version
I don't really like writing the change log automatically from commits. I think those both have a slightly different audience and thus need different wording.
I know the frustration of merge conflicts on the change log file.
Right now, I'm creating change logs by hand which is time consuming to do on release time. I'm considering switching to using towncrier or something similar, where you have a changes dir with one file per change for creating change logs --> https://towncrier.readthedocs.io/
The towncrier approach is similar to what we do at work. We have the addition that the individual changelog files say their scope (major, minor, or patch), and we use that to automatically compute the next version number.
version.txt
1.0.0
CHANGELOG
# 1.0.0
* Initial release
changelogs/add-foobar-api.md
minor: Add a new API call `foobar`
changelogs/improve-baz-perf.md
patch: Improve the performance of the `baz` API call
In the changelog compilation step it works out that the largest scope is minor, so the version of the next release is bumped from 1.0.0 to 1.1.0, and you end up with:
version.txt
1.1.0
CHANGELOG
# 1.1.0
* Add a new API call `foobar`
* Improve the performance of the `baz` API call
# 1.0.0
* Initial release
It works great, especially for large teams. You don't end up with lots of merge conflicts on the CHANGELOG file. The people writing the change get to describe the scope of the change (and that can be reviewed in the PR), rather than the person doing the release having to guess from the descriptions. Developers never have to worry about whether someone else has already bumped the version number or not.
There are a couple of aspects that can make lockfiles deceptive to look at
- Lockfiles include dependencies for all platforms, not just the ones you build with, including wasm and Hermit kernel
- Due to some quirks, lockfiles include more dependencies than will ever be used (related to a feature called "weak dependency features").
For a more accurate picture, look at `cargo tree` and `cargo tree --target=all`.
In this case, a lot of it is that the GitQL SDK depends on gix (gitoxide), a Rust re-implementation of git / libgit, which is made up of a lot of crates and depends on a lot of crates. This dependency should likely not be there and should be fixed. Even with `default-features = false`, gix pulls in a lot. Gix should not be relevant to a more generic SDK.
The other thing that stood out to me as unnecessary is that comfy-tables pulls in cross-term which has way too large of a dependency for what it is doing.
I am surprised at how much `chrono` pulls in but almost all of that is for specific platforms and `chrono` shrinks dramatically when looking only at the native platform.
I do see some stray dependencies that have built-in equivalents (lazy_static -> OnceCell, atty -> IsTerminal). Some of that is due to compatibility with old Rust versions. There were only a couple of these.
Blink support would use CSS animations which requires a deeper level of integration than the other SGR parameters so I wanted to hold off until I could iterate over a solution with a user. If you'd like to use Fancy-ANSI with blink support, please let me know on GitHub and I can implement it fairly quickly.
Recently did something similar in Rust but for generating SVGs. We've adopted it for snapshot testing of cargo and rustc's output. Don't have a good PR handy for showing Github's rendering of changes in the SVG (text, side-by-side, swiping) but https://github.com/rust-lang/rust/pull/121877/files has newly added SVGs.
That said, I am wanting a Github action based release workflow and want it to scale to manual edits of changelogs, so this is insufficient for me. Instead, I've been taking notes on changelog fragments as I hope they can offer the best of both worlds, see https://github.com/epage/epage.github.io/issues/23