using gh release to publish themes / beneficial for custom themes ?

[parmentelat]

as of today, to the best of my knowledge, one can use an alternate/custom theme by specifying in myst.md e.g.

site:
  template: https://github.com/myst-templates/book-theme/archive/de4c1e9c09c6cd12fc529c1f22e8abf8e7f35381.zip

in this example, the zip file is produced by essentially 2 pieces

• a gh action
  https://github.com/jupyter-book/myst-theme/blob/main/.github/workflows/release.yml
• which in turn uses the topelvel Makefile
  https://github.com/jupyter-book/myst-theme/blob/main/Makefile

the effect of which being to create a commit in each of the 2 'ghost' repos

• executablebooks/myst-article-theme
• executablebooks/myst-book-theme

the content of that commit being then retrievable through github's /archive/ route

---

the purpose of this issue is to propose the use of the GH releases instead, which would imho

• make this workflow simpler for the official themes : in particular
  • no need for the ghost repos
  • and a clearer web interface to browse through available releases/versions
  • also get rid of Makefile and group all the code in the gh actions
• but also make it simpler for forked instances of the official theme - typically for people who simply to do small changes - to publish themselves, as they could just use the exact same action without having to change or provision anything

---

I have made some preliminary work along these lines that are rather encouraging here
https://github.com/flotpython/myst-theme/blob/gh-releases-mystmd-2317/.github/workflows/gh-release.yml
and the resulting artefacts are browsable here
https://github.com/flotpython/myst-theme/releases
(only the book flavour is available in this POC)

so I'd love to hear from the core team to see if that could be of interest, and to hear about any pitfall that I have not identified at this point
I reckon my understanding of the theme fetch/download code is minimal; plus I have only considered book/article and have no idea about the other available themes

[parmentelat]

an additional benefit, users would be able to refer to tagged template using the tag name as in

template: https://github.com/executablebooks/myst-theme/releases/download/the-tag/book.zip

[parmentelat]

which btw raises another, partially unrelated question:
imo it would be nicer if a given version of mystmd came with a pinned version of its default themes, instead of relying on the latest published ones, that might just break stuff for older versions
but that's probably for another issue altogether..

[rowanc1]

@parmentelat I think this would be awesome to move to this pattern of releases for the theme.

I think the myst-template resolver will need a bit of work to look for the zip file in a new place, but the URL looks a lot cleaner...!

If you could help investigate how we can get there that would be awesome. Right now this is all done through the makefile, and builds in a .deploy folder, so I think it really wouldn't be that different a github action - the main difference I think is that the template download code in myst-templates package will need to change (probably starting only for those two themes?).

Probably some things to figure out, but this is really promising direction!

[parmentelat]

thanks @rowanc1

I just created a first PR in the theme repo

trying to plan for the overall change to complete, one possible transition path could be

• 1. add this new workflow (the above PR)
• 2. revisit executable-books/mystmd so that thearticle and book templates get located under the new scheme
• 3. after a while the older release.yml workflow can be dismantled, together with toplevel Makefile

notes

• about 1. - note that the new workflow triggers only on tag push, so I believe it would be mostly harmless to merge the PR early
• about 2. - as I mentioned my feeling is it would be beneficial if each shipped version of mystmd came with a pinned version of its associated themes - 2. would be the right time to introduce that I believe
• about 3. the current PR does not yet address the 'publish to npm' part that was in release.yml

[parmentelat]

about 2.:

when using e.g.

template: book-theme

the MystTemplate object first fetches this API endpoint https://api.mystmd.org/templates/site/myst/book-theme

where it finds details on where the book-theme is deployed, and as part of the answer it finds this

            "download": "https://github.com/myst-templates/book-theme.git",

and then on these lines
https://github.com/jupyter-book/mystmd/blob/main/packages/myst-templates/src/download.ts#L171-L178
because the URL is a .git, it gets rewritten in the /archive/ URL, namely into

https://github.com/myst-templates/book-theme/archive/refs/heads/main.zip

---

1. question

who has control on the contents of https://api.mystmd.org ?
would it be ok to define an alternative name - even on a temporary basis - so we can experiment with the alternative gh-release workflow, by simply defining another name in the API

2. proposal

in order to extend downloadTemplate()'s ability to deal with the new scheme, I would propose to use e.g. the .release suffix; this means one would define the theme with a download key as being instead

    "download": "https://github.com/jupyter-book/myst-theme/book.release"

that downloadTemplate() would then rewrite into

https://github.com/jupyter-book/myst-theme/releases/download/main/book.zip

one could argue that this url (the one that ends in .release) makes no sense; it's true that it would as-is return a 404
I'd reply that the current scheme indeed uses a valid URL but it does not actually use it for any actual purpose, so I don't think it's a problem

[parmentelat]

Hey @rowanc1

may I have your feedback on the above 2 points ?

if we can go along the proposed route, the 2 related PRs essentially implement the whole scheme
(except for the additions in the API - that I don't yet know how to address..)

[parmentelat]

a short update in this topic:

• support theme URLs that end in .release #2344
  I just rebased it on top of main, added a changeset, got most checks to pass (except for the label that I believe I'm not allowed to set)
• publish through GH releases myst-theme#659
  rebased as well, I didn't add a changeset as 'all checks have passed' but I can if that's helpful

let me know what else I can do to get this through