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.

Create a new branch for your changes

git checkout -b feature/your-feature-name

Make your changes. Commit each change with a clear commit message
```
git add .
git commit -m "Add feature X or fix bug Y"
```

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.

Releases & maintenance branches#

Releases of Gambit are made by core developers. Details of previous releases can be found in the GitHub releases page.

Branches labeled maintX and maintX_Y, where X is the major version number and Y is the minor version number, are associated with releases and point to the latest commit on a stable version. Navigate to the Gambit repository on GitHub and select the branches tab to see the list of active maintenance branches. Be sure to delete any maintenance branches that are no longer being maintained.

Making a new release#

When making a new release of Gambit, follow these steps:

Create a new branch from the latest commit on the master branch named maintX_Y, where X is the major version number and Y is the minor version number of the new release.
Update the version number in the GAMBIT_VERSION file at the root of the repository to X.Y.Z.

All other files will automatically use the updated version number:
- pyproject.toml reads from GAMBIT_VERSION file at build time
- configure.ac reads from GAMBIT_VERSION file and substitutes into Info.plist and gambit.wxs
- src/pygambit/__init__.py reads from installed package metadata or GAMBIT_VERSION file
- doc/conf.py reads from GAMBIT_VERSION file at documentation build time
- Documentation pages reference the |release| substitution variable to automatically reflect the updated version number.
Update the ChangeLog file with a summary of changes
Once there are no further commits to be made for the release, create a tag for the release from the latest commit on the maintenance branch.
```
git tag -a vX.Y.Z -m "Gambit version X.Y.Z"
```
Push the maintenance branch and tags to the GitHub repository.
```
git push origin maintX_Y
git push origin --tags
```
Create a new release on the GitHub releases page, using the tag created in step 4. Include a summary of changes from the ChangeLog file in the release notes.
Currently there is no automated process for pushing the new release to PyPI. This must be done manually.

Patching maintained versions#

If you have bug fixes that should be applied across maintained versions:

Make a branch from the oldest maintenance branch to which the change applies
Apply the change and make a pull request to that maintenance branch
After the pull request is merged, open new pull requests to each subsequent maintenance branch and finally to the master branch, merging each in turn
Create new releases from each maintenance branch as needed, following the steps in Making a new release.

Software tools for game theory.