Contributing to Gambit#

This section provides guidelines for contributing to Gambit, including how to report bugs, suggest features, and contribute code. It includes information relevant to both core developers and external contributors.

GitHub issues#

In the first instance, bug reports, feature requests and improvements to the Gambit documentation should be posted to the Gambit issue tracker, located at gambitproject/gambit#issues. Use the issue templates to help you provide the necessary information.

When reporting a bug, please be sure to include the following:

  • The version(s) of Gambit you are using. (If possible, it is helpful to know whether a bug exists in both the current stable/teaching and the current development/research versions.)

  • The operating system(s) on which you encountered the bug.

  • A detailed list of steps to reproduce the bug. Be sure to include a sample game file or files if appropriate; it is often helpful to simplify the game if possible.

Contributing code#

Gambit is an open-source project, and contributions are welcome from anyone. The project is hosted on GitHub, and contributions can be made via pull requests following the standard GitHub workflow.

In the git repository, the branch master always points to the latest development version. New development should in general always be based off this branch. Branches labeled maintX_Y, where X is the major version number and Y is the minor version number, point to the latest commit on a stable version.

  1. To get started contributing code in the Gambit GitHub repo, do one of the following:

  • Core developers: request contributor access from one of the team

  • External contributors: fork the repository on GitHub.

  1. Clone the repository to your local machine

    git clone https://github.com/gambitproject/gambit.git  # or your fork URL
cd gambit

  2. Follow the instructions in the Building Gambit from source page to set up your development environment and build Gambit from source. If you only plan to make changes to the PyGambit Python code, you can skip to Building the Python extension.

  3. Create a new branch for your changes

    git checkout -b feature/your-feature-name

  4. Make your changes. Commit each change with a clear commit message

    git add .
git commit -m "Add feature X or fix bug Y"

  5. Push your changes to your fork or branch

    git push origin feature/your-feature-name

  6. Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues.

  7. Core developers will review your changes, provide feedback, and merge them into the master branch if they meet the project’s standards.

Testing your changes#

Be sure to familiarise yourself with Contributing code before reading this section.

By default, pull requests on GitHub will trigger the running of Gambit’s test suite using GitHub Actions. You can also run the tests locally before submitting your pull request, using pytest.

  1. Install the test dependencies (into the virtual environment where you installed PyGambit):

    pip install -r tests/requirements.txt

  2. Navigate to the Gambit repository and run the tests:

    pytest

Adding to the test suite#

Tests can be added to the test suite by creating new test files in the tests directory. Tests should be written using the pytest framework. Refer to existing test files for examples of how to write tests or see the pytest documentation for more information.

Editing this documentation#

Be sure to familiarise yourself with Contributing code before reading this section.

You can make changes to the documentation by editing the .rst files in the doc directory. Creating a pull request with your changes will automatically trigger a build of the documentation via the ReadTheDocs service, which can be viewed online. You can also build the documentation locally to preview your changes before submitting a pull request.

  1. Install the docs dependencies (into the virtual environment where you installed PyGambit):

    pip install -r doc/requirements.txt

  2. Navigate to the Gambit repo and build the docs:

    cd doc
make html  # or make livehtml for live server with auto-rebuild

  3. Open doc/_build/html/index.html in your browser to view the documentation.

Recognising contributions#

Gambit is set up with All Contributors to recognise all types of contributions, including code, documentation, bug reports, and more.

You can see the list of contributors on the README page of the Gambit GitHub repo.

To add a contributor, comment on a GitHub Issue or Pull Request, asking @all-contributors to add a contributor:

@all-contributors please add @<username> for <contributions>

Refer to the emoji key for a list of contribution types.