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.

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.

Clone the repository to your local machine

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

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.
[Optional but recommended] Install pre-commit which is used to run code formatters and linters before each commit. This helps ensure code quality and consistency. You can install it into the virtual environment where you installed PyGambit
```
pip install pre-commit
```
Alternatively, pre-commit is also available via various packaging systems. For example, you can install via Homebrew
```
brew install pre-commit
```
If you install via a package manager (instead of into the virtual environment), pre-commit will be available for use with other projects.

Then, set it up in the Gambit repository
```
pre-commit install
```
Having pre-commit installed is recommended as it runs many of the same checks that are automatically conducted on any pull request. Every time you commit, it will automatically fix some issues and highlight others for manual adjustment.

Create a new branch for your changes

git checkout -b feature/your-feature-name

Make your changes.
```
git add <files>
git commit -m "Clear and descriptive commit message"
```
Provide a clear commit message. Gambit does not have its own set of guidelines for commit messages. However, there are a number of webpages that have suggestions for writing effective commit messages (and for deciding how to structure your contributions as one or more commits as appropriate). See for example this page.

Push your changes to your fork or branch

git push origin feature/your-feature-name

Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues.
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.

Install the test dependencies (into the virtual environment where you installed PyGambit):
```
pip install -r tests/requirements.txt
```
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.

Install Pandoc for your OS
Install the docs dependencies (into the virtual environment where you installed PyGambit):
```
pip install -r doc/requirements.txt
```

Navigate to the Gambit repo and build the docs:

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

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

Contributing tutorials#

To submit a tutorial for inclusion in the Gambit documentation, please follow these steps:

Open a GitHub issue using the Tutorial request issue template on the Gambit GitHub repo or choose an issue already opened with the tutorial label.
Write the tutorial as a Jupyter notebook (.ipynb file), following the style and format of existing tutorials in the doc/tutorials directory. Develop this on a branch as per the instructions in Contributing code. Add the tutorial to the doc/tutorials directory in the repository. Put it in an appropriate subdirectory or create a new one if necessary.
Update doc/pygambit.rst to ensure the tutorial is listed in the docs at an appropriate location.
[Optional] If your tutorial requires additional dependencies not already listed in doc/requirements.txt, please add them to the file.

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.

Software tools for game theory.