Document how to add (or move) packages

[fingolfin]

The README should explain how one can add a new package. And we should make it as easy as possible.

(More generally, this covers the process of depositing packages into the GAP package distribution)

In fact right now I don't think we have a good way. The only I can think of is to manually add a package/NAME/meta.yml file by copying an existing file and editing the PackageInfoURL, then running scan_for_updates.py. Clearly that's no good. There should be a tool add_package.py or import_package.py. It can share some code from scan_for_updates.py, esp. output_json and add_sha256_to_json.

Going one step further, ideally there will be a website where you have a form in which you past the URL of a PackageInfo.g file, press a button, and it creates a suitable PR to this repository. But we'll see.

I working on some of this right now

[fingolfin]

@hulpke requested to deposit https://www.math.colostate.edu/~hulpke/classicpres/PackageInfo.g so I'll use this as my test case for the new scripts

[fingolfin]

Here's my thoughts on how this process could work, in various variants. Note that I only consider how the new package gets in; the question of what hurdles it has to pass (besides obviously passing validation and tests) is separate (and kinda important; we definitely should discuss it at some point, too). Also: who is "allowed" to make the decision of accepting (or rejecting!) a package which was submitted for depositing (which is distinct from a submission for full review, of course)

1. Via command line and a PR (for power users / how it works internally)

   1. clone this repository
   2. run a script inside the repo clone: tools/import_packages.py SOME_PACKAGEINFO_G_URL or tools/import_packages.py PATH_TO_SOME_PACKAGEINFO_G
   3. this creates a new file packages/mypackage/meta.json: add that into a new branch and submit a pull request. From the command line and using the gh tool this would do it: git checkout -b mypackage && git add packages/mypackage && git commit -m "Deposit mypackage" && gh pr create

2. Via workflow trigger (convenience for people with access to this repo)

   • we could have a GitHub workflow which is run by a manual trigger and takes a package URL as input. It would then basically execute the steps described above. But I could do it from e.g. my web browser, and it is fully automated for me

3. Via an issue (for regular uses with a GitHub account)

   • they could (and should) simply open an issue on this repository requesting the addition of their package. This is the natural way to go about this for people who don't mind having this in public. Then someone else can create the relevant pull request. (We should perhaps have a list of people who explicitly agree to feel responsible for this! I certainly will, but it would be good to have more, so I don't become the new bottleneck)

4. Via email (for regular uses without GitHub account or who prefer privacy)

   • designate a mail address (could be the usual support@... or a new packages@... email) to which one can send requests to adding a package. Then "someone" (... see the previous point) will again create a pull request, and inform the email sender about this)

5. Via a webform??? (somewhat hypothetical)

   • in an ideal world, perhaps we'd also offer a public website were anyone can enter a PackageInfo.g URL, press a button, and the relevant PR is created. But this has to be carefully considered to prevent abuse. Also, I am not sure how much work it would be. Perhaps it could be done via a repository_dispatch webhook event. See e.g. https://mainawycliffe.dev/blog/github-actions-trigger-via-webhooks/ or http://www.btellez.com/posts/triggering-github-actions-with-webhooks.html
   • besides potential security issues, one concern with this is that it is completely anonymous (so 3rd parties could submit packages without the knowledge or consent of the package authors!).
   • also, without additional work, the submitter has no direct insight as to whether this worked, where to see the result, etc. Of course all this could be overcome, but I am not sure it is worth the effort.