Move package homepage to GitHub pages, use ReleaseTools?

[fingolfin]

I am not sure if you are interested in this at all, but perhaps you'd be interested in moving the homepage of this package to GitHub, using https://github.com/gap-system/GitHubPagesForGAP, and switch to using https://github.com/gap-system/ReleaseTools for releases.

The advantage of using ReleaseTools this is that the process of bundling a release gets super streamlined, while at the same time more reliable, as the release-gap-package script performs tons of sanity checks, which prevent many common mistakes people make when releasing new versions of their packages -- esp. when they don't make new releases all the time, but only once a year or so.

The advantage of hosting the package on GitHub is that maintenance can be automated (in fact, ReleaseTools can automatically update the website when a release is made). You can also get download statistics, if you like (albeit only in raw JSON format). You can also host older versions of the software here. And if needed, then others can help out (so if there is a bug fix, and a new release should be made, but you don't have time, you can ask someone else from the GAP Team to help out and make the release for you).

Note that you can use ReleaseTools without using GitHub Pages, it just means that you have to manually update your website after a release.

There are of course also drawbacks: you loose control, the homepage moves, it is not as integrated with your university account, etc. So if you are not interested, that's perfectly fine! But if you are, don't hesitate to ask questions, I am happy to help (and I am guess so is @alex-konovalov)

[jdebeule]

Thanks for the suggestion! Setting up the page was easy!

[fingolfin]

Cool, so now there is https://gap-packages.github.io/forms/ !

Question is, would you like to keep this in addition to http://cage.ugent.be/geometry/forms.php ? Or instead of it?

In the former case, it might be a good idea to add links between the two pages.

In the latter case, perhaps the "old" page could get a link to the new one. But more importantly, PackageInfo.g would have to be edited to use the new URLs -- otherwise GAP's package distribution automation won't be able to pick up the new version. (Oh and also the README and manual should get links to the "new" place).

Also, if you intend to use the new page from now on, then I would work on getting the GAP package distribution to pick up new forms versions from there (that just means creating a pull request editing https://github.com/gap-system/gap-distribution/blob/master/DistributionUpdate/PackageUpdate/currentPackageInfoURLList to change the forms URL).

[jdebeule]

I will just create a forward from http://cage.ugent.be/geometry/forms.php to https://gap-packages.github.io/forms/. Also because our universities will make it in the near future almost impossible to maintain small local pages like the forms one.

A practical question: I have the gh-pages directory inside ./pkg/forms/ now. Am I correct that I can also include this directory into the forms repository?

I will definitely start using the new page, https://gap-packages.github.io/forms/ I just would like to make some edits.

[fingolfin]

The gh-pages directory already is in the repository, on a separate branch. Do notattempt to add it to your master branch; at best it'll fail, at worst it'll cause havoc...

[jdebeule]

I see, well, so far, I didn't try ;-) But when I do 'git status', it says

git status On branch master Your branch is up to date with 'origin/master'.

Untracked files: (use "git add ..." to include in what will be committed)

gh-pages/

nothing added to commit but untracked files present (use "git add" to track)

So my questions was actually whether gh-pages should be tracked?

[fingolfin]

No it should be added to .gitignore. But if you change into that directory, you will see that it is also tracked by git

[fingolfin]

Sorry for being short. Writing this all on my phone with a baby on the lap tugging at me

[jdebeule]

I have been trying to use the ReleaseTools now. I managed to use the script a first time. Based on a warning (WARNING: unsupported archive format -win.zip) I made a change after the first time in PackageInfo.g (replacing -win.zip into .zip). After issuing

GAP=/usr/local/bin/gap4r11.1 ~/ReleaseTools/release-gap-package --force --no-push

I get the error

ERROR: tag v1.2.6 is not the HEAD commit -- did you tag the right commit?

Do I have to change the version number now? But that seems not logical, based on

"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 7, you now need to pass --force to the release-gap-package tool)" (step 7 of in the README of the Release Tools)

[fingolfin]

Writing from phone: try manually deleting the tag first, i.e. git tag -d v1.2.6

if that helps, please let me know, the error message should be made more helpful and also the README. Sorry about that.

[fingolfin]

OK, now am looking at this from my computer, and I am seeing this: a tag v1.2.6 exists on GitHub. But it points to a commit which is not on the master branch. So perhaps you did a rebase or otherwise rewrote history. The release tool does not (currently) override this even with --force as it's easy to loose work. But the error message it prints should make that clear (and perhaps --force should force a retag...)

In this case, though, I think it might be good that it did not override things: the v1.2.6 tag is actually ahead of master... Perhaps master was not pushed to the server? But I think release tools does that?!? (I didn't review that part of the code in a long time, though, I might misremember...). In any case, I see this:

$ git log v1.2.6
commit e4b3b1b6c572dbf6cfae3edc2f3d19861d8ff534 (tag: v1.2.6)
Author: Jan De Beule <jan@debeule.eu>
Date:   2021-07-09 17:22:04 +0200

    changed date in PackageInfo.g to release date

commit 8d2c8584cc171fc6a1c674445d2c65cb8bd4c715
Author: Jan De Beule <jan@debeule.eu>
Date:   2021-07-09 16:51:41 +0200

    last check of PackageInfo.g. Removed redundant author name in postal address.

commit b0a35a1017ebbaa212f8d6e45e164ec7ed11d4bd (HEAD -> master, origin/master, origin/HEAD)
Author: Jan De Beule <jan@debeule.eu>
Date:   2021-07-08 18:29:00 +0200

    added gh-pages to .gitignore
...

So one way to fix this would be to do something like the following (I am being extra defensive and careful here, as I don't know the state on your computer:

# retrieve any a
git fetch --all 

# switch to `master` branch
git checkout master

# at this point, perhaps check that your local master is identical to the remote one... 
# e.g. check output `git log` ...

# now, try to fast forward to the v1.2.6 commit:
git merge --ff-only v1.2.6

# if the above gave an error, let's discuss more. But if it works: you can continue as follows:
git push   # push the changes to master out to github

# now try to make the release again:
release-gap-package

[fingolfin]

@jdebeule if/when you find time to resume work on this (and I mean it: please don't feel pressured by this, I know how it is to juggle many obligations, and sympathize), feel free to contact me, perhaps we can have a video call (via Jitsi/BBB/Facetime/Zoom/Skype/whatever) and I can live assist. Also, feel free to join the "GAP Slack" (that's a kind of multi user chat system, with a bunch of GAP devs and users on, who can provide some assistance round the clock). Here's an "invite link" if you are interested: https://join.slack.com/t/gap-system/shared_invite/zt-sowqw2vb-DEaZ00Qx_ghfIywHcfqF9w

[jdebeule]

I will be back at work next Monday. The "problem" was the good weather this week: I took the opportunity to do some hikes in the mountains ;-) I will contact you again next week. A video call is a good idea, so we can quickly discuss some other questions I have (which can be posed much easier through a live meeting than by mail). About the forms package: I am sure that next wee we will have a release.

[olexandr-konovalov]

After https://github.com/gap-system/gap-distribution/pull/125, the new location was detected, but not picked up:

Package: forms
  new components: [ "AbstractHTML", "AcceptDate", "ArchiveFormats", 
  "ArchiveURL", "AvailabilityTest", "BannerString", "CommunicatedBy", "Date", 
  "Dependencies", "IssueTrackerURL", "Keywords", "License", "PackageDoc", 
  "PackageWWWHome", "Persons", "README_URL", "SourceRepository", "Subtitle", 
  "TestFile", "Version" ]
  changed components: [ "PackageName", "Status", "PackageInfoURL" ]
Package: Forms
# Error (/circa/home/gap-jenkins/pkgadmin/pkgcache/forms/tmp/tmpinfo.g): no pa\
ckage info bound!
  WARNING (Forms): no success in download of the current info file 
  from https://gap-packages.github.io/Forms/PackageInfo.g

The reason is that the repository is forms in lowercase, but package name is Forms. You need to use LowercaseString like e.g. I do in https://github.com/gap-packages/laguna/blob/master/PackageInfo.g.

[jdebeule]

A new release 1.2.6 has been uploaded, now using LowerCaseString as suggested

[olexandr-konovalov]

It will not work. https://github.com/gap-packages/forms/commit/8a3552d6165175b9566adbc457dc249de10fa66a only changes one field, which is the repository URL. This URL is not used to check for package updates at all - it is only used for displaying on the package overview page. What I need is the PackageInfo.g URL, which is still broken. Please see https://github.com/gap-packages/laguna/blob/master/PackageInfo.g - it uses LowerCaseString in several places. You may also notice how it reuses other fields from PackageInfo record to minimise chances of typos.

I still managed to pick up 1.2.6 but further process is broken, so any fixes should result in incrementing number to 1.2.7.

[olexandr-konovalov]

Hi @jdebeule Thanks, you made commit f6290fd63b565b35367f90b4f19a2fde68416921 for 1.2.7 but was it ever released? It still shows 1.2.6 everywhere. Could you please make a new release (or ask us to publish it), otherwise check for Forms updates fails.

[fingolfin]

This was done now, 1.2.7 is out, see #24