Preparing for v5.0

[axelboc]

We should probably release v4.2 v5.0 soonish. It's been 6 months since v4.1, and there's been quite a lot of changes. Since it's going to be a complex release because of the GUID changes, I thought we could coordinate things a little in this discussion thread.

First off, are we sure about bumping the minor version number even though users of the French and Norwegian decks will need special upgrade instructions? By releasing a major version, we would send a clear message to everyone that they need to pay close attention to the release notes.

Second, in #399 (reply in thread), I talked about creating a discussion thread for each release with specific upgrade instructions, and @aplaice you suggested placing these instructions on the wiki. I think you're right in the end: the wiki is better suited, especially now that it contains a couple of other pages. The discussion thread still makes sense to announce the beta release and to report problems, but it should link to the upgrade instructions on the wiki rather than include them directly.

I'm going to create the wiki page, but if you don't mind @aplaice, I might let you write the actual instructions for v4.1.1 and v4.2, since they will involve SQL queries...

Plan of action

• 1. Create SQL queries for changing GUIDs of French and Norwegian decks as per Support installing the deck in every language in the same Anki profile #415
• 2. Write upgrade instructions for v4.1.1 to v5.0 and v4.1 to v4.1.1
  • Include a section explaining how to check whether one is on v4.1 or v4.1.1
  • Include SQL queries (in HTML <details> blocks?)
• 3. Finish off outstanding issues and PRs - e.g. Add more flag similarities #429
• 4. Proceed with release (write release notes, publish beta, etc.)

[axelboc]

I've created the wiki page but I'm not 100% sure how to structure it: https://github.com/anki-geo/ultimate-geography/wiki/Upgrade-instructions... I went with "from" headings, thinking that the instructions depend more on which version you're coming from rather than which version you're going to. Does that make sense? 🤷

I'm also not sure how to reference the upgrade instructions contained in the README, which contain valuable information and can apply regardless of version-specific instructions.

[aplaice]

Does that make sense? shrug

At the moment that makes sense! Later on we'll probably encourage users to upgrade stepwise (probably with headings like "upgrade from 4.1 to 5.0" etc.) to avoid a complicated update matrix, but I'm not sure — we can think about that once we come to it.

[aplaice]

First off, are we sure about bumping the minor version number even though users of the French and Norwegian decks will need special upgrade instructions? By releasing a major version, we would send a clear message to everyone that they need to pay close attention to the release notes.

I think you're right, having a major release might be sensible under the circumstances. It's not like we'll catch up with, say, Chrome or Firefox with our major version numbers. :)

I'm going to create the wiki page, but if you don't mind @aplaice, I might let you write the actual instructions for v4.1.1 and v4.2, since they will involve SQL queries...

Yeah, I'll do it! I'm not sure how much time I'll have in the next week, so no promises on when I'll have it done by.

in HTML <details> blocks?

That would be best. (The alternative is linking to external gists, but it's probably preferable for the instructions to be self-contained.) (Inline, without <details> blocks isn't really an option...)

---

Thanks for kicking off the process and for the summary/suggestions!

[axelboc]

Awesome, thanks! I've made some minor edits, feel free to revert/edit again.

[axelboc]

For other upgrade scenarios, I feel like we need a version matrix or something 😂 ... so people know by how many versions they can "safely" upgrade. Like, if you're on v3.3, can you upgrade to v4.1 directly, or do you have to go through v4.0? Alternatively, we just tell people to ask us in the Discussions 😄

[aplaice]

Awesome, thanks! I've made some minor edits, feel free to revert/edit again.

Thanks! The edits look great!

For other upgrade scenarios, I feel like we need a version matrix or something

Hmm. I think that other than the v3.3 → v4.0 upgrade, which might be problematic due to the removal of some cards, there's nothing that we really need to warn users about.

We could perhaps copy the part of the v4.0 release notes concerned with upgrading, into the wiki? We could also add a heading saying that the v3.3→v5.0 update is essentially v3.3→v4.0 + v4.1.1→v5.0. In essence, something like:

# From v3.3

## To v4.0

<copy part of v4.0 release notes more-or-less verbatim>

## To v5.0

To upgrade to 5.0, if you don't want to lose progress, you need to:

1. Read the instructions for [upgrading to v4.0](link) and follow the part concerning importing the "legacy deck". You do not need to import the v4.0 deck itself as an intermediate step. (It doesn't hurt, but it also won't help.)
2. Follow the instructions for [upgrading from v4.1.1 to v5.0](...link...).

If you have any doubts please ask in [Discussions](https://github.com/anki-geo/ultimate-geography/discussions) (for instance, in the thread dedicated to the release) or open an issue!

?

---

In some cases, duplicate decks will be created (i.e. the deck "container" will be duplicated; the contents won't — it's exactly the same issue as updating from an AnkiWeb standard deck using CrowdAnki). For instance, this will happen in some v4.0 → v4.1.1 upgrades (and consequently also v4.0→v5.0 etc.) due to the deck crowdanki_uuid becoming the same for all decks irrespective of language (due to brain-brew's design choices). I've mentioned this in the v4.0 upgrade section.

[aplaice]

I ended up just linking to the v4.0 release notes, for the "from v3.3" section, to avoid large-scale copy-pasting...

[axelboc]

Awesome, this looks great. I've added a mention of the clean import in the intro, just so people know that's always an option.

[aplaice]

The topic of the legacy deck from v4.0 reminded me:

We're again removing two cards from the deck (the capital of the EU, ×2), in such a way that existing users will lose those cards. Do we care about this sufficiently to create another "legacy deck", with one note (and two cards), that users could import to keep the cards?

(My opinion is "definitely not" (it adds far more confusion than it's worth), but I thought I'd bring it up, in case somebody strongly disagrees.)

[axelboc]

Yeah, seems like a lot of effort for not much, I agree.

[axelboc]

I've drafted the release notes for v5.0, let me know what you think, and give the upgrade a try! https://github.com/anki-geo/ultimate-geography/releases/tag/untagged-752eaa83e276de8920d6

---

Now that multiple maintainers can see draft release notes thanks to the new GitHub org, and now that we use Discussions like we are right now, I wonder whether the beta release workflow is still worthwhile. In the end, I feel like publishing a beta release is just as dangerous as publishing the final release: we still might get people upgrading before we have the time to notice a major issue (whether in the upgrade instructions or in the deck itself). What do you think?

I'm quite liking this process so far of opening a discussion to prepare the release: we can plan the remaining work, proof-read the draft release notes, and try the upgrade ourselves with the ZIPs attached to the draft release notes. This should catch most problems, shouldn't it?

[axelboc]

Damn, that's annoying. Oh well, here are the v5.0 standard and extended English decks if you want to try them out 😉 :

• Ultimate_Geography_v5.0_EN.zip
• Ultimate_Geography_v5.0_EN_EXTENDED.zip

[horwitz]

No worries—thanks for trying. I suspect I'll wait on the release notes (I've definitely found them very helpful in the past), but thanks for the links

[ohare93]

I also cannot see it! 🤔 Ah! Now it is there. Strange

[aplaice]

Thanks for creating the list of contributors! :)

---

I've tested multiple combinations of upgrades and I think everything works fine!

---

I'm having doubts about the Upgrade Instructions section that I wrote — looking at the first few paragraphs of the "All other languages" section, it looks like one only needs to worry if one has the buggy "v4.1.0" deck, which isn't the case for French and Norwegian. (Obviously, the v4.1.1 section is just below and the issue is also mentioned in the release notes, but if one just clicks the "Upgrade instructions" link, skims the section that's immediately visible and tries to upgrade directly afterwards one might not encounter the full explanation before hitting a problem.)

Consequently, I've added this:

Additionally, if you're upgrading the French or Norwegian deck and you wish to keep your progress, you'll need to run a (different) debug console script also when upgrading from the non-buggy version of the deck ([see just below for details.](https://github.com/anki-geo/ultimate-geography/wiki/Upgrade-instructions#french-or-norwegian-bokmål)).

just below the "Debug console snippet to determine if you have the buggy v4.1".

I hope this won't make the page even more cluttered...

(Feel free to remove if you think it's redundant!)

(Perhaps I'm over-worrying, but I don't want to punish the French or Norwegians for the anki-dm bug any more than necessary...)

---

In the descriptions in the release zips, some of the statistics are wrong. :( (They're correct in the repository itself, in both places.) (It's not a blocker, though, IMO.)

- the world's 206 sovereign states (824 cards)
- 59 territories, world regions, and other entities (105 cards)
- 39 oceans and seas (39 cards, maps only)
- 7 continents (7 cards, maps only)
- for a total of 311 unique notes, 975 cards, 222 flags and 311 maps.

vs.

- the world's 206 sovereign states (824 cards)
- 59 territories, world regions, and other entities (103 cards)
- 48 oceans and seas (48 cards, maps only)
- 7 continents (7 cards, maps only)
- for a total of 320 unique notes, 982 cards, 222 flags and 320 maps.

[axelboc]

Ah well spotted, thanks. I have to build the English deck once and import it to find the updated stats in the Anki browser, then I have to rebuild the decks once I've actually updated the stats in desc.html. Not the smoothest of processes... 😅 I need to add this to the maintainer's guide so I don't forget 😄

Thanks for adding the clarification in the upgrade instructions. Better safe than sorry!

I'll do the official release this week-end.