I wrote a handful of template packages at the start of this year and would like to fix a few issues in them, but to be honest I’ve been putting it off because I don’t understand the monorepo organisation of typst universe and how one is meant to submit packages to it / update submissions later on.
Is there a simple guide to submit a PR for a package on typst universe, that does not require making a fresh fork of the entire repo each time? (That’s what I resorted to – a new copy of the entire thing every time).
Ideally I’d want to have one repo for each of my packages and submit changes from those, one at a time independently.
I remember seeing a guide automating this with GH actions etc. but it had a lot of steps and was overkill for me (I don’t need to automate releases from a tag etc. – just make a PR manually from my own repos). Is there a simple guide somewhere?
1 Like
Updating should not be very difficult. Here is how I do it on a package (templates follow the same process as far as I know.)
You should have initially forked the package repo from typst. You can update your fork with the “sync fork” button on GH. Then you clone your fork locally (or git pull if you already have it) and make all the changes you want to the template (directly on the main branch or on a separate branch that you then merge to main). When you are ready, push all your changes and open a PR to merge your fork to the main repo.
You probably have to do that for each template separately because you should have one fork for each, but I might be wrong.
There might be much better processes, but this is simple enough for me with good git experience but limited GH experience.
Having one fork for each package seems a really big hurdle, considering the size of Typst universe. That’s why I’m hoping for a better workflow somehow.
One fork with multiple branches suffices. You can also do a --depth 1 clone to skip the history (though it’s of course still a bit of a heavy repo).
We’re aware that the package submission process is not the simplest and we want to have a more direct way in the future. But that would require a whole lot of engineering which we can’t prioritize at the moment. Using GitHub as an stopgap solution gives us a lot of things for free (e.g. review tooling).
4 Likes
Thanks – oh, I see, so if I understand correctly I should make a separate branch for each package I want to do a PR on.
I still wonder if/how it possible to use one’s own repo (with just the one package) and somehow make a PR to add it to the whole package repo. I think I once saw a tutorial some months ago that was describing it, but I can’t find it again (it was probably linked on Discord).
You can reduce the size of the repo further with a sparse-checkout.
Something like
git clone --depth 1 --no-checkout --filter="tree:0" git@github.com:typst/packages
... // cd into the folder
git sparse-checkout init
git sparse-checkout set packages/preview/[your-package-name]
git checkout main
Then you have something like (this is for glossarium), all in all the repo is 7MB on disk.
❯ git count-objects -v
count: 0
size: 0
in-pack: 3638
packs: 4
size-pack: 1745
prune-packable: 0
garbage: 0
size-garbage: 0
To answer the original question:
- I have a repository for the package, e.g., GitHub - typst-community/glossarium: Glossarium is a simple typst glossary.
- I publish a release on GitHub on the package’s repository
- I archive every file that is needed for the package, removing examples and docs, etc. (glossarium/package.sh at master · typst-community/glossarium · GitHub)
- I extract the archive on my fork of typst/packages (up-to-date if possible) and commit the new version.
- Open a PR for the new release
9 Likes
As an addendum, for future releases, if you already have the packages project cloned (shallow), then you can follow the 2 steps below to make sure you are up-to-date before opening a PR.
Note that this is destructive in nature.
git fetch upstream --depth=1
git reset --hard upstream/main
where upstream is simply the typst/packages.
git remote add upstream git@github.com:typst/packages
# OR
git remote add upstream https://github.com/typst/packages
You will probably also need to overwrite your remote (origin), where origin points to your fork.
git push --force origin
1 Like
I wrote a simple shell script to handle publishing and updates for new and existing packages based on the methods discussed here. It’s been working great for my own workflow, so I wanted to share it for anyone still looking for a solution.
View the GitHub gist here:
Basically, you’d configure the information for your package repository, set to use either ssh or http protocol for repository access and then run the script from your package git repository (not the fork).
username="my_github_username"
package_name="my_package_name"
repository=$package_name
packages_fork_name="packages"
ssh="git@github.com:"
http="https://github.com/"
upstream="${http}typst/packages"
packages_fork_address="${http}$username/$packages_fork_name"
The script’s process is as follows:
- Deletes local clone of the fork, if it exists
- Creates a new local clone of the fork (hereafter referred to as “fork”)
- Updates fork with latest commit from upstream
- Creates a new branch
- Adds package files to fork
- Removes unnecessary files
- Commits all files for that new version
- Pushes the new branch upstream for PR
Notes:
-
The only “requirement” is a VERSION file to avoid editing the script every time, but the version can be set directly before each run.
# Use a VERSION file to retrieve version numbers.
version=$(<VERSION)
# OR write the version number directly.
# version="0.0.0"
-
Each run of the script creates a fresh clone of the fork so as to prevent conflicts with other packages on your system.
-
The git push command is --dry-run by default for testing and to prevent accidentally pushing upstream.
# NOTE: This is a test. Remove `--dry-run` to actually push your code upstream.
git push --dry-run origin $new_branch # --force # <-- Overwrite branch on origin.
-
The script handles the removal of any PDFs, backup files (*.bak, *.bkp), temporary files (*.tmp, *.temp) and test files before publishing upstream. This does not affect actual repository files, but of course these commands can be removed as necessary.
4 Likes