ReleaseTools for GAP packages
The scripts in this repository along with this README are meant to help GAP package authors with the process of making new releases of their packages. The problem with making releases is that it is quite easy to forget steps, which can cause a lot of extra work if you later need to correct that. Moreover, if one only makes a release once a year, it is easy to forget how this works -- making the release process an often unwelcome and tiresome process.
The goal of this document and the tools shipped with it is to help GAP package authors to automate this process as much as possible, so that making a fresh release of a package becomes a quick and painless undertaking.
These tools are focused on making releases for packages hosted on GitHub, and which are using the GitHub release system as well as GitHub pages for the package homepage.
release script should run on any POSIX compatible system,
provided the following tools are available:
- Python 2.6 or later
- BSD or GNU tar (for creating
- zip (for creating
In addition, you also need a recent version of GAP (4.7.8 or later
should do it). By default the
release script assumes that there is a
gap executable in your PATH. If this is not the case, or if you want
release to use another GAP executable, you can do so via the
For example, you could invoke
release like this:
Your package must also be hosted on GitHub.
Finally, you need a GitHub access token, which the script uses to authenticate with GitHub, so that it gets permission to upload files for you. For details, please read section "GitHub access token" later in this README.
The following steps should be performed once on your package repository. After that, you can follow the instructions in the next section to make a release.
Setup GitHubPagesForGAP for your package, as described in its README.
PackageInfo.gfile to use GitHub. This may require adjusting
ArchiveURL. An easy way to do that is to use the following in your
PackageInfo.g. It assumes that your package name is equal to the repository name; note that case matters. Also, you may have to replace "gap-packages" by your username (the generated URLs must match the URL of your package's repository).
SourceRepository := rec( Type := "git", URL := Concatenation( "https://github.com/gap-packages/", ~.PackageName ), ), IssueTrackerURL := Concatenation( ~.SourceRepository.URL, "/issues" ), PackageWWWHome := Concatenation( "https://gap-packages.github.io/", ~.PackageName ), README_URL := Concatenation( ~.PackageWWWHome, "/README" ), PackageInfoURL := Concatenation( ~.PackageWWWHome, "/PackageInfo.g" ), ArchiveURL := Concatenation( ~.SourceRepository.URL, "/releases/download/v", ~.Version, "/", ~.PackageName, "-", ~.Version ),
Update your README, your package manual etc. to use the correct URLs.
makedoc.gGAP file which regenerates your package manual. If you are using GAPDoc, often the AutoDoc package provides an easy way for doing this, as in the following example:
if fail = LoadPackage("AutoDoc", "2016.02.16") then Error("AutoDoc version 2016.02.16 or newer is required."); fi; AutoDoc();
As a fallback, we also looks for a
doc/make_docexecutable. If found, we assume the package is not using GAPDoc, but rather still uses a manual based on the
gapmacroTeX macros. We then execute the
make_docscript from inside the
docdirectory, and copy relevant files.
The release process
Suppose we want to release version 1.2.3 of a package named
Suppose furthermore that directory
foo contains a clone of the
In order to make a release, you can follow the steps below. Note that this
gap is in your PATH, i.e. it can be invoked by just entering
gap. Alternatively, before running the
release tool you can set the
environment variable to contain the full path to your GAP executable
Make sure we are on the right branch and have the latest version.
cd foo && git checkout master && git pull
You should also verify that there are no uncommitted local changes, and if there are, either commit them or remove them.
Make sure there is a
gh-pagessubdirectory which contains an up-to-date checkout of the
gh-pagesbranch of your repository.
Power users with a recent git version (2.7.0 or later) can also use
git worktreeto create the
Update the version and release date in
Adjust the release date and version in your manual. Note that AutoDoc can do this automatically for you (please consult its manual to learn more).
Make sure that any files containing the version and release date are updated (e.g. the manual; your
Commit all your changes to
VERSION, documentation, etc., e.g.:
git commit --all -m "Version 1.2.3"
Create the release using the
releasescript included here:
If this does not work, please refer to the section discussing
Verify that everything went fine by visiting https://github.com/USER/FOOBAR/releases/tag/v1.2.3 and https://USER.github.io/FOOBAR
In particular, test the release archives created by the previous step. If you are unhappy with the outcome, or for some other reason decide that you need more changes, do these and go back and repeat previous steps as necessary (in step 8, you now need to pass "--force" to the
Update the website:
cd gh-pages && git push
releasewill also do this for you if you call it with the
That's it. You should now be able to see the new version on
and also be able to view the manual there, download the new version
should be up-to-date. So if the GAP server already has this registered
as location of your
PackageInfo.g, it should now automatically
detect that you made a release, and pull it into the next
GAP package bundle.
release script helps you create release archives of your GAP package in a clean
and controlled way, and publish them on GitHub.
Again, we assume you are working on version 1.2.3 or package
Invoking the release script
You normally invoke
release as follows from inside a clone of your
This scans your
PackageInfo.g for the package name and version, and
uses that to guess the release tag.
--tag: By default, the script assumes that you tagged your release with a tag named
v1.2.3in our example). If you prefer to use other tag names, you can specify this as parameter, e.g.
PATH/TO/ReleaseTools/release --tag VER-1-2-3
Note that the
releasetool will attempt to verify your tag by checking it against the
--token: Set the GitHub token to use. For details, refer to section "GitHub access token" in this README.
What it does
release script does multiple things for you:
It creates archive files in a subdirectory
tmpof the current directory. For now, it knows how to create
.zipfiles. Which it creates depends on the
ArchiveFormatsfield of your
The files by default are
tmp/PACKAGENAME-VERSION.tar.gzetc., so in our example we would get
However, the script also look at the
ArchiveURLfield of your
PackageInfo.gto decide if a different basename was chosen. So if you prefer the archives to be called
then you can achieve this by editing your
To create these archives,
git archiveto export precisely the files in your repository present in the commit tagged
v1.2.3. This ensures that only files that are present in your repository will be added, no more, no less; and that no stray local changes are included by accident.
After exporting all files, a few more steps are performed: a. It removes any
.gitmodulesfiles. b. If a script
autogen.shis present, it is executed. c. If a file
makedoc.gis present, it is executed. Various files like
doc/*.auxare removed afterwards. d. Otherwise, if a file
doc/make_docis present, it is executed. Various files like
doc/*.auxare removed afterwards.
It uploads the created files to GitHub for you.
TODO: Describe details
It updates various files in the
gh-pagessubdirectory to help you with updating the website. In particular, it copies the
gh-pages, and also copies the HTML version of the manual it just built for the release archives to
gh-pages/doc. Finally, it runs the
update.gscript to regenerate
GitHub access token
release script needs limited write access to your repository in
order to upload the release archives for you. In order to do this,
the scripts needs to authenticate itself with GitHub, for which it needs
a so-called "personal access token". You can generate such a token as follows
(see also https://help.github.com/articles/creating-an-access-token-for-command-line-use).
Click Generate new token.
Select the scope "public_repo", and give your token a descriptive name.
Click Generate token at the bottom of the page.
Copy the token to your clipboard. For security reasons, after you navigate off the page, you will not be able to see the token again. You therefore should store it somewhere, e.g. with option 3 in the following list.
There are multiple ways to tell the
release script what your token is. In
order of their precedence (from highest to lowest), these are:
--tokencommand line option:
./release --token VALUE ...
Set the environment variable
TOKENto the token value. This is mainly useful in scripts. E.g.
TOKEN=VALUE ./release ...
Add the token to your git config, by setting
github.token. As usual with git config entries, you can set this globally in your
~/.gitconfigor locally for each clone (which can be handy if you need different tokens for different projects). You can set the token via the following commands:
git config github.token VALUE # for the current project git config --global github.token VALUE # globally
For details, please refer to
git help config.
Create a file
~/.github_shell_tokencontaining your token and nothing else. If you do this, make sure this file is not readable by other users, i.e., run
chmod 0600 ~/.github_shell_token
Please submit bug reports, suggestions for improvements and patches via the issue tracker.
You can also contact me directly via email.
Copyright (c) 2013-2017 Max Horn