In-app release notes

[jesseduffield]

Is your feature request related to a problem? Please describe. In the next release we'll be making quite a few changes that might disrupt users, such as:

• Cherry picking now uses shift+C and shift+V instead of c and v to support the 'v' keybinding everywhere for selecting ranges
• Likewise the 'v' keybinding is no longer supported for viewing the divergence of a branch from its upstream from within the upstream options menu (need to use enter instead)
• Hitting escape when in range select mode in the staging view will now cancel the range select rather than exit the staging view
• The background range selection style config has been removed: instead we're just using the same background style that we use for a single selected item

It would be nice to have an easy way to advertise these changes to users after they update so that they're not surprised (or, failing that, so that they only have themselves to blame for ignoring the heads-up).

Describe the solution you'd like I would like to be able to show release notes from within lazygit, such that release notes appear automatically after the user updates.

This could involve storing the current lazygit version on startup and then checking that upon next startup to see if there's a difference. If there is a difference, we show a release-notes popup.

Rather than duplicate release notes both in github and in the code, we can have lazygit fetch the release notes from github.

We can use a package that renders markdown using ANSI escape sequences. E.g. https://github.com/charmbracelet/glamour/

Describe alternatives you've considered Release notes aren't a perfect solution to the original problem: they contain much more information than just 'what are the breaking changes you should know about' so there's a lower signal-to-noise ratio than having a bespoke popup message saying exactly what to look out for. But they have other benefits:

• Users may simply want to know what's happening in the repo
• Contributors get more recognition because they'll be seen by a larger number of users

So I think that on net it's a good idea.

I think users who build from source and track the master branch should not get the popup because their version will just change too frequently and that would be annoying. You should also be able to configure to not get the popup.

Additional context I've got a very hacky draft branch for this (https://github.com/jesseduffield/lazygit/compare/release-notes). I don't expect I'll have much time to work on it in the near future so if somebody wants to pick it up, let me know!

[stefanhaller]

I have to say I'm not convinced that showing the full release notes in a lazygit window is a good idea. For larger releases they are going to be too long, and while it's cool that we have the technology to approximate the markdown layout using terminal escape sequences, it just won't look as good as on a web page; especially when you include demo videos like you did for the 0.40.0 release.

My feeling is that it's better to have bespoke text that just mentions the breaking changes, with a link to the full release notes.

[mark2185]

Having release notes is a very nice touch, at least for me it's much more interesting to see what work is being done (and that it is being done in the first place) instead of just "less bugs, more fixes" (if anything).

And as much as I love terminals and TUIs, I'd rather have a list of major and/or breaking changes, e.g. like the cherry picking mappings changing, and a link pointing to the rest of changes.

Anyone interested in reading more can visit the release page + it seems wiser to delegate that to a browser that can handle it without fuss, instead of adding yet another dependency and the codebase becoming even bigger.

Stefan's right, we should ask ourselves "should we", not just "could we".

[jesseduffield]

Fair enough. One major benefit of having the release notes pulled straight from github is that we don't need to do duplicate the release notes when we cut a release.

Nonetheless I take your points and I'm happy to just have bespoke text and a link to the release notes. The question is: how should we implement this? Here's what I'm thinking:

When the user updates from say version v0.40.0 to v0.41.0 we need to show them all the release note links from v0.40.0 (exclusive) to v0.41.0 (inclusive). And if any of those releases have a bespoke message associated with it, we need to show that too.

The current version is baked into the binary so we can store the current version on startup as LastVersion so that on next startup we can compare the two. If there is a last version (meaning this isn't the first time you're opening lazygit) and it's a release version (e.g. v0.40.0 and not some commit hash) and the current version is also a release version, then we'll talk to github to get all the tags and find out which tags fall between the old and new versions.

Here's what that looks like in curl:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHubC-Api-Version: 2022-11-28" \
  https://api.github.com/repos/jesseduffield/lazygit/git/matching-refs/tags/v

[
  ...
  {
    "ref": "refs/tags/v0.40.1",
    "node_id": "MDM6UmVmMTM0MDE3Mjg2OnJlZnMvdGFncy92MC40MC4x",
    "url": "https://api.github.com/repos/jesseduffield/lazygit/git/refs/tags/v0.40.1",
    "object": {
      "sha": "579791e7bc8261e9ed578f882f4b8b11a486bf78",
      "type": "commit",
      "url": "https://api.github.com/repos/jesseduffield/lazygit/git/commits/579791e7bc8261e9ed578f882f4b8b11a486bf78"
    }
  },
  {
    "ref": "refs/tags/v0.40.2",
    "node_id": "MDM6UmVmMTM0MDE3Mjg2OnJlZnMvdGFncy92MC40MC4y",
    "url": "https://api.github.com/repos/jesseduffield/lazygit/git/refs/tags/v0.40.2",
    "object": {
      "sha": "5e388e21c8ca6aa883dbcbe45c47f6fdd5116815",
      "type": "commit",
      "url": "https://api.github.com/repos/jesseduffield/lazygit/git/commits/5e388e21c8ca6aa883dbcbe45c47f6fdd5116815"
    }
  }
]

We need to extract out just the tag names, sort them, then filter down the list to just the tags we want to show.

Now, for some releases we'll want an in-app bespoke message, but for some (e.g. patch releases) it's fine to just link to the release. And I say that specifically because I'm lazy and I don't want to have to edit the source code each time I cut a new release.

In english.go we can define a struct for storing bespoke messages:

type TranslationSet struct {
  ...
	ReleaseMessages ReleaseMessages
}

type ReleaseMessages struct {
	V0_41_0 string
}
...
  V0_41_0: "Warning: this version changes some keybindings. The cherry pick copy/paste keys have been changed from 'c'/'v' to 'shift+C'/'shift+V', so that we can use 'v' for selecting a range of commits blah blah"

We'd then use reflection to check, for each release we're including in our popup, whether there exists a matching message in the RelaseMessages struct. ~~We may not need to use reflection: we could define ReleaseMessages as a map[string]string but we'd need to ensure this works with our i18n merging logic (that is, if the user is using the Chinese language, and a given release message is not defined in chinese.go, we fall back to the english version).~~ (EDIT: let's just use reflection)

Importantly, I want to make it very easy to add these release messages: when I want to add a new release message, I should be able to just modify english.go and have everything work.

So in the end we'll end up with a popup that looks like:

You are now on version v0.41.0

v0.41.0:
  Warning: this version changes some keybindings. The cherry pick copy/paste 
  keys have been changed from 'c'/'v' to 'shift+C'/'shift+V', so that we can
  use 'v' for selecting a range of commits blah blah

  Release notes:
  https://github.com/jesseduffield/lazygit/releases/tag/v0.41.0

v0.40.2:
  Release notes:
  https://github.com/jesseduffield/lazygit/releases/tag/v0.40.2

v0.40.3:
  Release notes:
  https://github.com/jesseduffield/lazygit/releases/tag/v0.40.3

If there's a network error when retrieving the tags from github, we'll show an error toast and record the new version, meaning we will not attempt to show the release notes on next lazygit start.

One thing that's nice about this is that we can append to the release message as part of a PR which makes a breaking change, but the message won't appear until the actual release goes out.

What do we think?

[stefanhaller]

Fantastic, this is a great breakdown of how this should work. I agree with everything.

As for the english.go file, I vote for using reflection rather than a map, because then we're sure that it'll work fine if/when we switch to CrowdIn (#3070). A map may or may not work as well, but I'm not sure.

[jesseduffield]

Cool let's go with reflection then

[jwhitley]

With the repo path cache PR waiting for review, I can start working on this issue this week, probably starting today or tomorrow. Feel free to assign it to me. I've been minding the conversation to-date, and the chosen approach seems straightforward. As always, I'll drop in with questions should any arise.

[afhoffman]

I was thinking about this a little bit. It seems like in a lot of apps these popups appear when I don't have time to check them out and then I have trouble figuring out how to get the pop-up back again when I do have time to check it out.

What do y'all think about having this pop-up also appear when you click the version number in the bottom right?

That way those who configure to not see these pop-ups automatically could get them on demand, and those who realize they were interested only after their finger already hit Esc can get the pop-up back easily.

[stefanhaller]

We could do that, although I'm not sure how discoverable this would be (i.e. how many people would try to click on that version number). If we underline it, maybe.

I would rather have suggested to add a link to the release notes to the status view, but it's in there already...

[afhoffman]

Yes I agree if it was underlined like "Donate" and "Ask Question", it would be more discoverable.

I saw it in the status view too, but I feel like that view is also kind of easy to miss in that what shows in the box on the left hand side (current repo & branch name) isn't super related to what shows up in the main view when it's selected (information about lazygit).

Anyway, just a small thought that might be nice if it's an easy add, Definitely not something worth putting a ton of effort into!

[jwhitley]

As a stake in the ground, since focusing on the Status view already shows lazygit's "About" page I'm planning to simply append the bespoke release notes proposed here to the end of that view. Thus:

• Per the spec above, a release-notes only pop-up appears on first run of a different version.
• The full release notes content is always available at the bottom of the Status view. Even on small terminals, it looks like this will be "above the fold".

I'm happy to change course, but this seems like the most user-familiar place that currently exists for ongoing access to the new content.

[jesseduffield]

@jwhitley that works for me

[jwhitley]

@jesseduffield I'd like to discuss the release process as you see it relating to this feature, specifically the transition from pre-release (unreleased on master) to a versioned release. As a motivating example, one pattern relevant to this case is to use a label in ReleaseMessages ala VNEXT that accumulates messages until a release is cut, then at release time:

• The content of VNEXT is promoted to the now-named release version (e.g. V0_50_0)
• VNEXT itself remains but is now the empty string
• The above process could optionally be automated. I'm not terribly familiar with goreleaser, but it seems like this should be doable?
• VNEXT otherwise doesn't exist regarding the pop-up logic. Assumption: local builds of lazygit should never trigger the "just updated" logic, nor update the latest version run in state.yml
• VNEXT content would however always be the "latest" version in the Status/About dialog.

[jesseduffield]

I'm not clear on the problem that VNEXT solves. Your assumption is right in that local builds (i.e. where the version is a commit hash) will never trigger the just-updated logic or update the version in state.yml.

Given that fact, I don't actually see why we need a concept of VNEXT. If somebody adds a PR which introduces a breaking change, they would just add a new version which is one minor bump up from the current one and put the breaking-change message there. When we eventually release that version, the message will appear in a popup.

[stefanhaller]

@jwhitley How is it going with this? Anything I can do to support the work?

I'm also wondering if we should reduce the scope of this considerably to give it a better chance of actually getting done. For example, we could scratch the whole idea of asking github for releases, and only focus on showing our bespoke "breaking changes" messages. I mean, who is going to click on 7 separate release notes links anyway? Just show them one link to the notes of all releases (like today in the status view). The downside is that they need to pay attention to when to stop reading themselves, but I'd say that's not so bad, if we tell them very clearly which version they were updating from.

This should simplify the whole thing dramatically, as we can do all the work locally based on the stored last version.

Any thoughts?

[stefanhaller]

@jwhitley Since I didn't hear back from you, I went ahead and made a PR with the simplest possible implementation of this feature: #3377. Hope you don't mind!

[stefanhaller]

Addressed by #3377.

[jwhitley]

Thanks so much for stepping in here @stefanhaller, and sorry I dropped off. I got caught by a big mess of IRL stuff when I thought I would have plenty of dev time. 😞 I'll work on being better about communicating around that kind of thing going forward, but will stick to getting on helping w/ reviews etc. first.