ways to make releases easier and better

[joyously]

In regards to releasing a version of code in a repo, are there commands (or maybe templates?) that help with that? An example is to make release notes by retrieving all the descriptions of a range of commits, either a branch, or since a tag or date.
Would this be a command or a flag on log, or something in config that runs on a hook?

Related is something I've wondered about concerning the difference in Bazaar vs. Git regarding the hooks on commit. Bazaar merge is combining two versions, and it's not "saved" until you use commit. This lets you resolve conflicts and run tests before the commit. Git, is the opposite, where the merge generates a commit, and doesn't complete if there are conflicts, and you have to run tests on a pre-commit hook or something.
I'm not sure I understand how jj does this, with all the rebasing.

My interest is in facilitating good practices for releasing code. (Just today, I saw a project release 0.8.0 and very quickly have to release 0.8.1 for a quick fix that should have been caught prior to the release.)

[martinvonz]

Our release notes live in https://github.com/martinvonz/jj/blob/main/CHANGELOG.md. Everything under the "[Unreleased]" heading there is going to go into the next release. We try to keep that up to date as we make changes; we don't leave it for the person cutting the release to do all at once (the way the Mercurial project mostly does it, for example).

jj merge will create a new working-copy commit. If the merge includes conflicts, then you'd probably want to resolve those as soon as possible, but nothing prevents you from adding new commits on top.

[joyously]

Our release notes live in https:/...

Oh, I definitely was not asking about this project's releases. I was asking about jj commands for users to make their releases easier.

jj merge will create a new working-copy commit.

That's fine, but are there hooks or something about the workflow so that making a release catches things before release (or before commit)?

[martinvonz]

Oh, I definitely was not asking about this project's releases. I was asking about jj commands for users to make their releases easier.

Ah, I see :) Yes, the usual log command exists. Similar to Git, you can do jj log -r 0.7.0..main to see the commits in main that were not in 0.7.0, for example.

That's fine, but are there hooks or something about the workflow so that making a release catches things before release (or before commit)?

There are no hooks at all. The test suite catches most problems. That's also run by GitHub Actions on different platforms and configurations. Since jj is still a young project, we don't do release candidates yet, but I suppose we will start doing that some day.

[joyously]

There are no hooks at all. The test suite catches most problems.

Again, I am not asking about this project, but looking at how jj can help users with their project releases. The nature of Bazaar is to merge and then commit. Git has a pre-commit hook, so you can run tests or something. What does jj do to help with this?

[necauqua]

Well, technically the answer to the question you asked - nothing, there are no pre-commit hooks (at least yet) or anything similar to that.

That being said, using pre-commit hooks is definitely NOT the best practice to catch typo bugs like in your example, the entirety of CI exists for that, the automated release process should include running all the tests and whatnot, and building the artifact should happen in deterministic environment of the runner. I've actually never seen pre-commit hooks used in any project I've worked on ever (although I'm sure somebody uses them).

For example, the jj workflow - you make feature pull requests, and CI runs all the tests on the branch, if all checks are green it is mergeable. It does not depend on developer running or forgetting to run tests locally on his machine (which also differ significantly too). Then at some point, you create and push a release tag (not sure this is exactly how jj does it, but this is one of the most common workflows) and the CI builds and releases (e.g. on GitHub Releases) a version. The master branch is protected and nobody can just push to it, and even in single-developer projects CI can run tests when something was pushed to master.

Pre-commit hooks are only good to run something lightweight like the linter (depending on the size of the project too) to avoid unnecessarily spinning up the CI runner when you just typoed something - and yes, in good robust workflows the CI even checks the codestyle and rejects poorly formatted merge requests.

For merges, jj is exactly like git, except it does not fail on conflict and creates a special conflicted commit for which you resolve the conflicts and amend that resolution into the merge commit - or even just have the resolution as a separate commit, the conflict being forever visible - except well GitHub and everybody else don't know how to show those conflicted commits as this is a jj-native concept.

For the generating the changelog, jj's log is actually pretty powerful for that, there's the revset syntax to select a specific set of commits and there's an entire templating engine to format those commits to generate something changelog-like - although generating changelog straight from the VCS commits is not the best practice either.

[joyously]

That being said, using pre-commit hooks is definitely NOT the best practice to catch typo bugs like in your example, the entirety of CI exists for that, the automated release process should include running all the tests and whatnot, and building the artifact should happen in deterministic environment of the runner.

OK, it seems that you are referring to something else that I'm not aware of. My example was not a typo; it was an actual project that has tests and is built for several different targets. They had to do a quick fix because some of the keys in the UI didn't work. This wasn't caught before the release. Yet all of the advice out there is to have a main branch and a release branch and do all the tests before merging into the main for the release.
I think the continuous integration is a separate thing that really ought to be more integrated, so the quality control team and the testing team can verify things before a release. Since there are so many different ways to work, and not all projects make releases, it is questionable how to make the version control system in charge of that, but the VCS is where all the data is for the versions, so it also seems like it should be the main player in that.

Perhaps instead of looking at what jj is today, look at what it could (and maybe should) be.
With Bazaar/Breezy, you merge, run tests and linters, etc. and only when it looks good, you commit. With jj, I just don't see the advantage of doing it like Git, but no hooks.

And if the log command is so powerful, maybe mention how to use it in real life, somewhere, so us newbies can know too.

[necauqua]

When I said 'typo bugs' I meant 'bugs that were caused by someone accidentaly breaking something obvious, but that was not caught by CI because they don't have CI and just push to master I guess' - that what I inferred from your initial example.

If this project you're talking about had a proper CI setup - this issue they had would not have been caught by any pre-commit hooks, well they just f-d up, it happens.

and only when it looks good, you commit

Thats absolutely not how it works in git/jj though. Commits are not set in stone, you can freely edit local history (in jj it's a tiny bit easier/more convenient, but it's the same essentially) and push/forcepush it to remotes.

What you mean by "commit" in that sentence should be "merge the pull request into master", the commit is just a checkpoint, while the "it looks good" part should be carried out by the CI and the reviewer(s).

You want to ensure (by pre-commit hooks) the developer runs the tests before pushing - but the developer shouldn't think about that, making a commit is a fast and lightweight operation, it should literally take no time - while running tests, especially locally, takes (relatively) forever, especially on the bigger projects. And a pre-commit hook is easily bypassed while the CI is enforcing.

Now, when you're done with the feature, you push the branch and make a merge request, and here all the checks are happenning (you can run the tests locally to be sure but that's optional). And the branch you want to merge can have multiple commits, again, those are just checkpoints, useful for mental separation of parts of the feature for example, individual commits are not as significant as you seem to perceive them as (or as they are in this bazaar thing it seems).

In both git and jj a commit is just a quick snapshot of the codebase. The job of the VCS is to manage those snapshots, the job of CI is to test everything that was pushed and to make releases.
It is not the job of the VCS to run tests/make releases - if I setup a project with a git repo and make a pre-commit hook that runs tests - well now making commits takes forever, it fails for different people (getting contributors in OSS will be a nightmare) all the time and is generally pretty brittle.

Anyway this is a useless debate, we're probably not changing each others minds, sorry for the essays, I tend to answer like that;
My point was that for the specific reason you've outlined ("good release practices") a pre-commit hook is not something necessary, and it shouldn't be the job of the VCS anyway.
And answering the direct question, jj will probably add support for git hooks in the future, but currently there is none.

Oh and the log thing, there are docs in this repo, as well as jj log --help 🤷

[arxanas]

With Bazaar/Breezy, you merge, run tests and linters, etc. and only when it looks good, you commit. With jj, I just don't see the advantage of doing it like Git, but no hooks.

Problems with pre-commit hooks:

• Users may not have them installed/configured correctly.
• Users can choose to bypass them.
• Pre-commit hooks may pass on one machine but fail on another. I’ve had frequent issues in the past where tests seemed to pass (or fail) on my machine but not on a coworker’s. In some cases, the tests were designed to test specific OS or software combinations which I don’t have on my machine. In those cases, we can’t rely on pre-commit hooks to verify that the tests pass (or even fail).
• Pre-commit hooks run on every commit, which is incompatible with the common workflow of using commits for draft purposes before they’re ready to be tested. Many commits may not even compile, let alone pass tests.
  • Sometimes this is due to using the VCS to snapshot broken code, but other times, this is due to a rebase on top of the latest main branch breaking local work.
  • This is especially cumbersome with jj, where the working copy itself is a commit. Would you run the pre-commit hook every time a change was made to the working copy?
  • From your description, it sounds like Bazaar/Breezy adopt the same philosophy as e.g. Fossil of never committing before everything works, which I think is sacrificing a lot of the power of a VCS.
• Pre-commit hooks are fundamentally serialized, which is inconvenient for local work with many commits (“patch stacks”). As an alternative, we are considering the design for a jj run command which can check commits in parallel (see On `jj run` #1486; I couldn’t find a discussion for jj run itself).
  • One interesting idea is that, in jj, we need not consider different situations for testing working copy contents vs other commits, since they are the same. This means that we can do things like cache results for the working copy in the same way as for other commits, or run remote builds/tests using a uniform interface for commits and working copy contents.
• Pre-commit hooks are fundamentally serialized, which makes it impossible to work at scales where commits arrive faster than the tests can be run. Large organizations use “merge queues” to batch and speculatively test larger units of code (making the assumptions that 1) most commits aren’t broken, and 2) if tests pass with the combination of all of a set of commits, then they pass for each individual commit — or at least, it’s not problematic to land all such commits together).

Note that many Git users also consider pre-commit hooks an anti-pattern for the above reasons. Personally, I view the move away from pre-commit hooks and towards systems like jj run to be the future of VCS, since we can take advantage of VCS features for many sophisticated workflows.

As far as a maintainer releasing a broken version of the software — I think this ought to be analyzed from an operations perspective rather than a strictly technical perspective. There was probably some reason that the maintainer felt that the code was ready to push. Perhaps they made a minor change that “shouldn’t” have affected anything, or wanted to skip the tests because they were slow? Maybe they wanted to run the tests but also start on other work, and it was inconvenient to occupy the working copy? Using remote CI workflows can alleviate some of these concerns, since you can “fire and forget” build and test jobs without inconveniencing yourself locally.

[arxanas]

And if the log command is so powerful, maybe mention how to use it in real life, somewhere, so us newbies can know too.

The Mercurial log command is similarly powerful. I think I figured out about it because I kept searching for things, for which every StackOverflow answer suggested using hg log (as opposed to Git, where you’ll need some choice of git log, git show, git rev-parse, git rev-list etc.). jj would probably benefit from a “workflows guide” or Q&A (which I guess Github Discussions is supposed to be? I’m not sure how well the answers are indexed on search engines.) to fill this niche. Perhaps we ought to start populating one of the two with common workflows, so that they can get indexed?