Document a way to generate/work with snapshots (and - possibly - publish them from CI)

[szpak]

Since the release of 5.0 (Sep 2021) there were some useful changes in the repo - in my case the Polish translations (which I need for my young cousins). Due to the (potential) migration issue, I understand that releasing too often brings also some inconvenience for the users. As a result, I propose to document a way how people could generate the snapshot versions of the package/deck locally or even better, to generate them for every master build on CI and publish it "somewhere" (just to play with - with no guarantee to cleanly update to the next version).

In a case, the generation is time consuming, it could be generated once a week (or so).

WDYT?

[aplaice]

(Terse answer, for now, sorry!)

The "build" instructions are in Contributing, though they're not too friendly for a casual user. (Additionally, I might not have updated them for the latest version of BrainBrew (the build step (the last "2" — the numbering is also messed up...) should be pipenv brain_brew run recipes/source_to_anki.yaml).)

Generating and "semi-officially" publishing the decks from master is an interesting idea! (CI actually does already generate the decks, as a test of well-formedness — we're just missing a publish step.)

[axelboc]

Releasing official versions is always quite time-consuming. I'll get the ball rolling for v5.1 at some point but can't give a timeline for now. So, yeah, a CI workflow that continuously builds and publishes an evergreen version of the deck somewhere would be amazing! Any idea where, though?

• GitHub CI artifacts come to mind right away, but they have a few downsides: 90-day limit (which might actually be enough, given that we usually merge a commit to the main branch more often than that); choice between one big ZIP file or listing every deck version in the workflow file; difficult to get to the download link(s) for people who aren't familiar with GitHub (likely our main target, given that power users can follow the CONTRIBUTING guide to build the deck themselves).
• Some external service? But then it must be free, obviously; and it can become complicated if a user account is required to set up and configure the service.

[ohare93]

One of us just auto publishing the deck to our own fork of the repo each time we will changes would surely work 🤔 then it can just be a link to there, for those that do not want to wait 🤷‍♂️

[szpak]

Thanks for your replies. I'm glad you like the idea :-).

The "build" instructions are in Contributing, though they're not too friendly for a casual user.

Thanks, I completely missed it. Maybe it would be good to mention that file in README?

GitHub CI artifacts come to mind right away, but they have a few downsides: 90-day limit

GitHub CI artifacts sound good to store "temporary" snapshot releases, especially that it is possible to also schedule a build once a week (or so), which should guarantee that there will be "something" still available even in a case of shortage of new commits to master.
Unfortunately, I agree that it might not be the most user friendly way to get those files - but maybe there are some "magic" links generated to the latest build.

One of us just auto publishing the deck to our own fork of the repo each time we will changes would surely work thinking then it can just be a link to there, for those that do not want to wait man_shrugging

That also is some solution workaround ;-). The downside is some extra effort to enforce the fork synchronization. And of course, it is not the most elegant solution (but as a stopgap :-) ).

[aplaice]

I've implemented a very rough method of publishing to a tag with GH actions. I haven't tested it too extensively, but it vaguely seems to work, automatically publishing to this release.

It uses this old, archived GH action. If there are issues, with it, it might be worth using the newer fork.

---

However, I don't think I'd feel comfortable using anything like this in the main repo — with secrets.GITHUB_TOKEN the GH workflow has full access to the repository (so if either our build process or the GH action* were compromised, an attacker could, say, rewrite history (technically trivial to spot by comparing with forks etc., but still...) or modify old releases).

* The code of the GH actions seems to be relatively straightforward so it'd be likely simple to spot evident malware in it, but still not easy to find a security vulnerability.

One can specify permissions for workflows (with permissions: ... in the YAML file), but it's very coarse-grained. One can make contents either fully read-only or fully read-write, so it's not possible to just allow modifying a single release (as opposed to allowing arbitrary changes to release/commits/tags etc.).

(OTOH Maybe I'm a bit too paranoid. :))

---

In the short-term I'll see how pushing new changes to the above, experimental branch (for auto-publishing) works, though. :)

---

Edit: Adding Italian seems to have worked!
Edit 2023-12-21: Merging in lazily/semi-automatically (via the "sync" button) seems to be still working!