On release, upload source code tarball to GitHub releases

[markwieczorek]

Problem

Once a github release is created, it is possible to download either a tarball or zipball of the source code from the releases page. These are generated automatically by Github, and are listed under the release assets as "Source code (tar.gz)" or "Source code (zip)" (see this example).

The problem is that these source code files are either regenerated each time you use this link, or that they are periodically cached and regenerated. This can give rise to a peculiar case where the hash of the file name changes, not because of changes to the source code, but to changes to the git references associated with the commit. This is a major problem when using third party package managers (such as macports and brew) that download this file and verify that the hash has not changed.

In the SHTOOLS project, the particular problem is related to using the versioneer package, which replaces strings in the pyshtools/_version.py file everytime that git archive is run to create the tarball. This can give rise to a change like this

diff -r SHTOOLS-4.7.1 SHTOOLS2-4.7.1
diff -r SHTOOLS-4.7.1/pyshtools/_version.py SHTOOLS2-4.7.1/pyshtools/_version.py
26c26
<     git_refnames = " (HEAD -> master, tag: v4.7.1)"
---
>     git_refnames = " (HEAD -> master, tag: v4.7.1, develop)"

which is only related to the fact that the develop branch was at the same commit as master when the release was created, and later, develop was no longer on the v4.7.1 tag. This problem is described more in this issue that is open at versioneer.

Solution

The solution to this problem is to make a copy of the tarball when the release is first generated, from this link: https://github.com/SHTOOLS/SHTOOLS/archive/v4.7.1.tar.gz

The next step would be to upload it as a binary asset to the release which will end up here: https://github.com/SHTOOLS/SHTOOLS/releases/download/v4.7.1/SHTOOLS-4.7.1.tar.gz

This can be done manually from the release page. However it would be desirable to incorporate this into the github release workflow by use of the existing file .github/workflow/pypi_publish.yml (this workflow should probably be renamed to just "publish").

There are several github actions on their marketplace for uploading assets to a release, but they are all poorly documented, and I can't figure out how they work in detail. Furthermore, there is dumb issue where the environment variable github.ref returns the tag like v4.7.1, but later we need to upload a file like SHTOOLS-4.7.1.tar.gz without the v. I am sure that there is a simple solution to this, but I haven't found it.