Submitting a Package

Packages distributed with GAP ship with it and are updated automatically when you release a new version. To submit a package for distribution, write to the GAP development mailing list or open an issue. If you are starting a new package, Creating a Package describes the recommended route.

A package does not have to be distributed with GAP to be used: PackageManager installs any package from its git repository or a release archive, and we list packages not distributed with GAP under Undistributed Packages.

How to submit

Send an email to gap@gap-system.org, or open an issue in the PackageDistro repository, giving:

  • the package name and a short description of what it does;
  • the URL of its PackageInfo.g file;
  • the URL of its source repository, if it has one;
  • how it relates to existing packages or library functionality, if it overlaps with any.

Anyone may do this on behalf of the package authors, but only with their consent. We forward submissions made as issues to the list.

The list is open. Anyone can subscribe, and subscribers can read all messages in its archive. You do not need to subscribe to submit: messages from non-members are held until a moderator releases them, which may take a day or two.

What happens next

Your submission is discussed on the list, where anyone can comment. The GAP team checks the requirements and replies there: we accept the package, say what needs to change, or decline it. Meeting the requirements is not enough on its own. We also consider whether the package is a useful addition to GAP, and its size, since the distribution is downloaded with GAP: we look closely at any package whose archive is larger than a few MB. A package we decline can still be listed under Undistributed Packages.

Once a package is accepted, it is added to the package distribution and ships with the next GAP release.

From then on, new versions are picked up automatically: we check the PackageInfoURL of each package every hour, so publishing a new PackageInfo.g and archive there is all a release needs. The version number must increase with each release.

Maintaining your package

We test distributed packages against new versions of GAP and of other packages. When something breaks, we tell you and usually send a fix; please review it and make a new release. If the GAP team co-maintains your package, we can make such releases ourselves; see Hosting your package on GitHub.

We may remove a package from the distribution at any time, for example if its maintainers do not respond to reasonable requests for releases needed to keep it compatible with GAP and other packages, or if it changes in a major way, such as growing much larger or adding functionality outside its original scope. A removed package can be submitted again.

Requirements

You do not have to check these yourself: when you submit, our automated tests check requirements 1, 2, 6 and 7, we review the rest, and we tell you what, if anything, needs fixing.

A package must

  1. have a PackageInfo.g that passes ValidatePackageInfo;
  2. be downloadable: PackageInfoURL, README_URL and every archive given by ArchiveURL and ArchiveFormats must be reachable, and each archive must unpack into a single directory without symbolic links;
  3. be distributed under a license compatible with GPL version 2, named in the License field and included as a file;
  4. have a manual that documents all functionality meant for users, built and included in the archive, with examples that actually work;
  5. have a non-trivial test suite, named by TestFile, that exercises the functionality of the package, including the manual examples; merely loading the package does not count;
  6. pass its tests both with all other distributed packages loaded and with only the packages it needs;
  7. load without errors or warnings, alone and together with all other distributed packages, and not change the behaviour of GAP or other packages; see Do not change the behaviour of GAP.

Getting help

If you have questions about submitting a package, or need help meeting a requirement, ask on the list, in the GAP Slack, in a PackageDistro issue, at GAP Days, or ask anyone from the GAP team you know. Help & Community compares these channels.

Checking your package locally

To find problems before you submit, you can run these checks yourself.

You need a GAP installation with all distributed packages installed and compiled; the release archive from the download page has them. Put your package into a directory, here DIR, and run the commands below. The first three exit with status 0 on success.

GAP 4.15 or newer. The option --packagedirs used below needs GAP 4.15 or newer. With an older GAP, put your package into the pkg directory of your GAP installation or into ~/.gap/pkg, and leave out --packagedirs DIR.

Validate PackageInfo.g (requirement 1):

gap -q -c 'if ValidatePackageInfo("DIR/mypkg/PackageInfo.g") then QuitGap(0); fi; QuitGap(1);'

Run the tests with all packages loaded (requirements 6 and 7):

gap -q --packagedirs DIR -c 'LoadAllPackages(); if TestPackage("mypkg") = true then QuitGap(0); fi; QuitGap(1);'

Run the tests with only the needed packages loaded (requirement 6):

gap -q -A --packagedirs DIR -c 'LoadPackage("mypkg" : OnlyNeeded); if TestPackage("mypkg") = true then QuitGap(0); fi; QuitGap(1);'

Here -A stops GAP from loading its default packages, and the OnlyNeeded option stops LoadPackage from loading your suggested packages. A test that fails only in this mode uses a suggested package without checking whether it is loaded; see Testing a GAP package.

If TestFile is a .g file rather than a .tst file, it must exit GAP itself with a status reporting the result, for example by calling TestDirectory with the option exitGAP := true. The Example package’s tst/testall.g shows how.

The CI workflow that PackageMaker sets up runs your package’s tests on every change to your repository, with GAP’s default packages and with only the needed packages, and can report which parts of your code the tests exercise. It does not run the other commands on this page. High coverage is encouraged but not a strict requirement.

List the variables and methods your package defines (requirement 4); ShowPackageVariables marks with * those that the built manual does not document:

gap -q -A --packagedirs DIR -c 'ShowPackageVariables("mypkg"); QuitGap();'

Check that none of the marked ones is meant for users; internal ones need no documentation.