Skip to content

Files

Latest commit

0f2e957 · Sep 27, 2023

History

History
122 lines (68 loc) · 11 KB

CONTRIBUTING.md

File metadata and controls

122 lines (68 loc) · 11 KB

Welcome to the typeset GAP package contributing guide

Thank you for investing your time in contributing to this package! ✨

In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.

Use the table of contents icon on the top left corner of this document to get to a specific section of this guide quickly.

New Contributor Guide

Welcome! To get an overview of the package, read the README. Here are some resources to help you get started with open source contributions:

Getting started

Issues

Create a new issue

If you spot a problem or find something you want to add, search if an issue already exists. If a related issue doesn't exist, you can open a new issue.

Solve an issue

Scan through the existing issues to find one that interests you. You can narrow down the search using labels as filters. See Labels for more information. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.

Types of Contributions

If you are looking to implement or extend the typeset framework, there are two main contribution paths you can take - creating a new package dependent on typeset, or via a pull request on this package repository. Steps for creating a new package can be found on the main GAP documentation, or through usage of the PackageMaker GAP package.

Creating a new package may be ideal for developers who want to implement several different things at once, whereas pull requests are likely more suited for developers whose sole goal is typesetting.

Supporting a new typesetting language

To implement the typeset framework for a new typesetting language, there are a small number of steps that should make the process as smooth as possible.

First, it is best to create a new directory named after the language within the gap sub-directory of this package - just to keep things organised!

Within this directory, you'll want to have at least two files, a lang.gd and a lang.gi. These files will follow the typical layout for GAP declaration and implementation files, and will contain the language-specific functions for your new implementation.

Once your files have been created, the next step will be implementing the operation to generate template strings for your language. As described in the documentation, the framework works by calling language-specific functions to generate language-specific template strings followed by populating them with a language-agnostic list of semantic features pertaining to the GAP object being typeset.

Therefore, you'll want to implement a method of the name GenLangTmpl (only the first letter of the language should be capitalised) for any and all of the types you're looking to typeset. It may also be a good idea to have a default fallback to the core GAP method String, as many objects may not even need any specific changes to get them typeset!

Beyond this template string generation, there may be a small number of other language-specific helper methods that will need to be created (e.g. CtblLegendLatex for character tables in LaTeX). This does depend heavily on the types of GAP objects you're looking to typeset and for most cases following what has been done in the LaTeX implementation of this framework should suffice.

With this, you should now have a working implementation of the typeset framework, congrats! 🎉

Now, before you can get all your changes committed, make sure to document your code and methods cleanly, and add tests to ensure everything you've written works as expected.

Documentation is fairly standard for GAP, and should at minimum include comments above declarations within .gd files, and some section header comments in your .gi files.

Make sure to add any new directories to makedoc.g under the scan_dirs record value or else it won't get picked up. Any new chapters and sections should also be added to order_info.g for documentation ordering purposes.

Tests should also be contained within their own language-specific directory under the tst sub-directory for consistency, but the range of tests you write is up to you and simply needs to prove that your implementation works as expected.

Extending support for new GAP types

Extending the package to support other GAP types (that may be implemented in other packages, or just not currently supported in the latest version) follows a slightly different process.

If you're looking to support a type implemented in another package, first decide if it's worth simply implementing the framework in the other package and making typeset a dependency. If not, it is preferred that support for these external packages are kept in separate files named after the package itself under the gap sub-directory.

To ensure the implemented methods are only installed if the external package is available, ensure you add a call to IsPackageMarkedForLoading when adding the new files to init.g and read.g.

If you're looking to simply add support for a type that is available as part of the GAP core distribution, then feel free to make additions to the files gap/typeset.gi and gap/typeset.gd.

As supporting new types is seen as language-agnostic, the main concern for you as a developer will be installing a new method for the operation GenArgs. At it's core, this method should return a list of strings that would likely be used to populate a template string representing this new type regardless of the typesetting language.

Of course, it may not always be possible to make this method perfectly generic, and if that is the case make sure to document exactly what else a developer would need to add to integrate your method into their implementation.

Beyond this, writing a new method for the operation GenLatexTmpl within the file latex.gi would provide a way for you to test if your GenArgs methods would integrate nicely, as well as provide an example for other developers. As LaTeX was the original focus of this package, this should be done before writing methods for other languages if possible.

Finally, before you can get all your changes committed make sure to document your code and methods cleanly, and add tests to ensure everything you've written works as expected. Documentation is fairly standard for GAP, and should at minimum include comments above declarations within .gd files, and some section header comments in your .gi files.

Make sure to add any new directories to makedoc.g under the scan_dirs record value or else it won't get picked up. Any new chapters and sections should also be added to order_info.g for documentation ordering purposes.

Tests should also be contained within their own language-specific directory under the tst sub-directory for consistency, but the range of tests you write is up to you and simply needs to prove that your implementation works as expected. Feel free to also write tests for the contents of GenArgs, there's no such thing as too many tests!

Making Changes

Make changes in the UI

Click the pencil icon at the top-right of any file to make small changes such as a typo, sentence fix, or a broken link (that only need one file to be edited). This takes you to the file where you can make your changes and create a pull request for a review.

Make changes locally

  1. Fork the repository.
  1. Install or update GAP to the latest version.

  2. Create a working branch and start with your changes!

Commit your update

Commit the changes once you are happy with them. Don't forget to self-review (i.e. check your changes work, documentation is good, tests are written etc.) to speed up the review process.

Pull Request

When you're finished with the changes, create a pull request, also known as a PR.

  • Fill the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
  • Don't forget to link PR to issue if you are solving one.
  • Enable the checkbox to allow maintainer edits so the branch can be updated for a merge. Once you submit your PR, a Docs team member will review your proposal. We may ask questions or request additional information.
  • We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
  • As you update your PR and apply changes, mark each conversation as resolved.
  • If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.

Your PR is merged!

Congratulations 🎉🎉

Once your PR is merged, your contributions will be publicly visible on the repository.