Skip to content

Latest commit

 

History

History
196 lines (142 loc) · 8 KB

DEVELOPING.md

File metadata and controls

196 lines (142 loc) · 8 KB
Raw

Developer guidelines

This document contains information potentially relevant for GAP developers. Please also check out the file CONTRIBUTING.md for getting started working on GAP. In contrast, this file here contains more specialized information that you can use like a reference manual.

Branches

At any time, there are two primary branches in the GAP git repository:

  • master: all new changes go into this; pull requests usually target it
  • stable-4.X (where X is some number): stable releases of the 4.X.* series are made from this branch

We are using GitHub's "branch protection" feature to restrict direct pushes to these branches. All changes should go through pull requests, to ensure that tests are run automatically and are passing (hard experience taught us that even "trivial" and "obviously correct" changes can break things).

Note that we only make releases from the most recent release branch; older release branches are kept around but we do not expect to e.g. make a new GAP 4.12.x release after 4.13.0 has been released, and so on.

Making changes to the release branch via backports

By default all changes go into the master branch. Once a release 4.X.Y is out, to get changes into the 4.X.(Y+1) release, the usual process is to first land them into the master branch, and have them "backported" later on the stable-4.X branch.

The process for backporting is as follows:

  1. someone adds the backport-to-4.X label to the pull request (if you don't have permission, just ask for someone, e.g. @fingolfin, to add the label)
  2. some time after the PR has been merged into master, and before the next stable release, someone will go through the list of merged PRs with this label, and backport them (usually by opening a dedicated backporting PR, which may contain the content of multiple PRs being backported).
  3. After a PR has been backported this way, the backport-to-4.X label is replaced by a backport-to-4.X-DONE label, to avoid processing it again (this is also important for our scripts which generate the changelog updates for releases).

Making changes to the release branch directly

Sometimes changes really are only for stable-4.X and not for master, usually because the two branches diverged sufficiently (e.g. code may have been rewritten in a major way on master which does not lend itself to backporting, but we still want to fix a bug in the old implementation for the release branch). In that case, you can create a pull request which directly targets the stable-4.X branch (the target branch can be selected on GitHub during the creation of pull requests). When making such a pull request, it's a good idea to point it out (and the reason) in the PR description.

Code formatting

Some simple rules for formatting code

  • no tabs
  • no trailing whitespace
  • all source files should end with a newline

This is automatically done if your editor honours our .editorconfig file. See https://editorconfig.org for a list of editors supporting this and how to configure them.

For historical reasons we have no particular rule for formatting code beyond the above. To avoid a chaotic mess, please adapt your contributions to the surrounding code. So if you insert something into a function that uses 2-space indentation, also use that.

Please refrain from reformatting code as you edit it, as this makes it much harder to review your changes. If you really must reformat something, do so in a separate commit which only contains formatting changes.

For completely new kernel code in C/C++, you can use clang-format to format it. If you edit existing code, you can try git clang-format (which reformats only code that is already modified). But here, too, please avoid large-scale reformatting, and keep reformatting in separate commits. The following command can sometimes help format just the code you modified anyway:

git clang-format $(git merge-base master)

Continuous integration (CI)

For every commit to our primary branches, and also for all pull requests, we use GitHub Actions to run the GAP test suite, in order to detect regressions early.

Which tests are run is controlled by the files .github/workflows/CI.yml and .github/workflows/release.yml. The syntax for these files and more is explained in the GitHub Actions documentation.

See also dev/ci.sh and other dev/ci-*.sh files for the scripts that are being run as part of these CI tests.

Discussions

GAP uses Slack, a multi user chat system, for discussions. Everyone can join via a web browser or a dedicated client (e.g for Android or iOS). Just follow the link https://gap-system.org/slack.

There is also an open developer list with currently very low volume. You can subscribe to it at https://lists.uni-kl.de/gap/info/gap.

Pull requests

Contributions to GAP should be done in the form of GitHub pull requests. Then our test suite (see "Testing" below) is automatically run as part of the "Continuous integration (CI)" tests (again see elsewhere in this file for details).

By default, your pull requests should target the master branch (see the section "Branches" for details).

We use labels on branches to help us generated release notes for new GAP versions. If you are a new contributor, don't worry about that, we'll take care of it (in fact you won't even have the access rights to set them -- again, don't worry about that).

If you do have the permissions to set labels, here are some guidelines:

  1. Always add one of the "release notes" labels.
  2. If the change is meant to be backported to the stable branch, add a "backports" label (see elsewhere in this document for details).
  3. Consider adding one of the "kind" label to indicate whether the change is a bug fix, enhancement or whatever else.
  4. Other labels are mostly optional and can help categorize things for the release notes. You are invited to set them but it's not a must.

Some other notes for pull requests

  • please read the section on "Code formatting"
  • try to focus your pull request, i.e. ideally don't change multiple unrelated things in one PR (this makes reviewing your changes easier).

Releases

For details on how GAP releases are made, see dev/releases/README.md.

Testing

GAP includes a test suite inside the tst directory, which is split into multiple parts.

  • testinstall: quick test suite that one can test frequently. Run via ./gap tst/testinstall.g
  • teststandard: slower but more comprehensive test suite. Run via ./gap tst/teststandard.g
  • testextra: very slow test suite that tests even more Run via ./gap tst/testextra.g
  • testbugfix: additional small test files that are created to verify specific bugfixes work as intended Run via ./gap tst/testbugfix.g

Tracking down regressions

The script dev/bisect.sh can be very helpful in tracking down which commit introduced a regression. Please read the extensive comments in the file to learn what it does and how to use it.

Vendored dependencies

GAP contains copies of some third party software, mostly to make it easier to build GAP "out of the box", with its minimal dependencies included. GAP maintainers may wish to update these dependencies from time to time.

  • extern/gmp: copy of GMP, the GNU Multiple Precision Arithmetic Library
  • extern/zlib: copy of zlib, a compression library used to implement transparent reading and writing of .gz compressed files.
  • hpcgap/extern/gc: copy of the Boehm garbage collector used by HPC-GAP
  • hpcgap/extern/libatomic_ops: copy of libatomic_ops, a subproject of Boehm GC; should thus be kept in sync with that.
  • cnf/config.guess and cnf/config.sub: used by our configure script. Ideally autoconf or autoreconf should automatically install the latest versions of these, but this doesn't happen (presumably due to a bug in autoconf). They can be updated by running the update-config.sh script inside the cnf directory.