From fc4e3d610ced424a32ecacf9e5f9c2156612e737 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 11 Nov 2025 11:13:47 +0000 Subject: [PATCH 1/6] add pytest instructions to contributing guide --- doc/developer.build.rst | 2 -- doc/developer.contributing.rst | 15 +++++++++++++++ tests/requirements.txt | 1 + 3 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 tests/requirements.txt diff --git a/doc/developer.build.rst b/doc/developer.build.rst index 596fc6ea6d..de58d0ac62 100644 --- a/doc/developer.build.rst +++ b/doc/developer.build.rst @@ -188,8 +188,6 @@ Use `pip` to install from the **root directory of the source tree**, optionally python -m pip install . -There is a set of test cases in `src/pygambit/tests`, which can be run -using `pytest`. Once installed, simply ``import pygambit`` in your Python shell or script to get started. diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index 07ae2e83e3..c0d4cd362f 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -61,6 +61,21 @@ version. 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 +^^^^^^^^^^^^^^^^^^^^ + +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. If you haven't already, install the test dependencies: :: + + pip install -r tests/requirements.txt + +2. Navigate to the Gambit repository and run the tests: :: + + pytest + + Editing this documentation -------------------------- diff --git a/tests/requirements.txt b/tests/requirements.txt new file mode 100644 index 0000000000..7ea8fcfacb --- /dev/null +++ b/tests/requirements.txt @@ -0,0 +1 @@ +pytest==9.0.0 \ No newline at end of file From 350c50e020b7f477fe489120fa9c089823e18496 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 11 Nov 2025 11:24:31 +0000 Subject: [PATCH 2/6] Update contributing guidelines to link to setup instructions for building Gambit from source --- doc/developer.build.rst | 6 ++++-- doc/developer.contributing.rst | 12 +++++++----- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/developer.build.rst b/doc/developer.build.rst index de58d0ac62..9316c6b101 100644 --- a/doc/developer.build.rst +++ b/doc/developer.build.rst @@ -181,11 +181,13 @@ Building the Python extension The :ref:`pygambit Python package ` is in ``src/pygambit`` in the Gambit source tree. We recommend to install `pygambit` -as part of a virtual environment rather than in the system's Python. -Use `pip` to install from the **root directory of the source tree**, optionally including the `-e` flag for an editable install: +as part of a virtual environment rather than in the system's Python (for example using `venv`). +Use `pip` to install from the **root directory of the source tree**: .. code-block:: bash + python -m venv venv + source venv/bin/activate python -m pip install . diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index c0d4cd362f..f8e5b1f272 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -45,21 +45,23 @@ version. git clone https://github.com/gambitproject/gambit.git # or your fork URL cd gambit -3. Create a new branch for your changes :: +3. Follow the instructions in the :ref:`building-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 :ref:`build-python`. + +4. 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 :: +5. 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 :: +6. 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. +7. Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues. +8. 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 ^^^^^^^^^^^^^^^^^^^^ From a326eb70b440794602c8c89a2bd39eb4325a481b Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 11 Nov 2025 11:32:47 +0000 Subject: [PATCH 3/6] simplify docs editing process --- doc/developer.contributing.rst | 27 +++++++++------------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index f8e5b1f272..714b61aff3 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -69,7 +69,7 @@ Testing your changes 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. If you haven't already, install the test dependencies: :: +1. Install the test dependencies (into the virtual environment where you installed PyGambit): :: pip install -r tests/requirements.txt @@ -79,32 +79,23 @@ You can also run the tests locally before submitting your pull request, using `p Editing this documentation --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. If you haven't already, clone the Gambit repository from GitHub: :: +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. - git clone https://github.com/gambitproject/gambit.git - cd gambit - -2. Either install the docs requirements into your existing PyGambit development environment, or create a new virtual environment and install both the requirements and PyGambit there. For example, you can use `venv` to create a new environment: :: +1. Install the docs dependencies (into the virtual environment where you installed PyGambit): :: - python -m venv docenv - source docenv/bin/activate + pip install -r doc/requirements.txt -3. Install the requirements and make the docs: :: +2. Navigate to the Gambit repo and build the docs: :: - pip install . cd doc - pip install -r requirements.txt make html # or make livehtml for live server with auto-rebuild -4. Open ``doc/_build/html/index.html`` in your browser to view the documentation. - -5. Make any changes you want to the `.rst` files in the ``doc`` directory and rebuld the documentation to check your changes. - -6. Follow the usual GitHub workflow to commit your changes and push them to the repository. +3. Open ``doc/_build/html/index.html`` in your browser to view the documentation. -7. Core developers will review your changes and merge to the master branch, which automatically deploys the documentation via the ReadTheDocs service. .. TODO: Add instructions for the GitHub workflow during contributor docs refactoring. See https://github.com/gambitproject/gambit/issues/541 From 748e14c56f7357d0df12c186c5c4306cf97ce2a5 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 11 Nov 2025 11:39:06 +0000 Subject: [PATCH 4/6] increase subheader levels --- doc/developer.contributing.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index 714b61aff3..24859ba4c3 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -64,7 +64,9 @@ version. 8. 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 :ref:`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`. @@ -79,7 +81,9 @@ You can also run the tests locally before submitting your pull request, using `p Editing this documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------- + +Be sure to familiarise yourself with :ref:`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. From e2b6bc67c0c4cedcfc052d423a92f82a644f04d8 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Tue, 11 Nov 2025 11:48:32 +0000 Subject: [PATCH 5/6] add note on adding new tests --- doc/developer.contributing.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index 24859ba4c3..d120daadfc 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -79,6 +79,13 @@ You can also run the tests locally before submitting your pull request, using `p 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 --------------------------- From f22975859c24ae26df7a1a53b3399b52e18953e8 Mon Sep 17 00:00:00 2001 From: Ed Chalstrey Date: Wed, 12 Nov 2025 10:15:58 +0000 Subject: [PATCH 6/6] add section to recognize contributions and guide on using All Contributors --- doc/developer.contributing.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index d120daadfc..bdd86f42a5 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -111,3 +111,15 @@ You can also build the documentation locally to preview your changes before subm .. TODO: Add instructions for the GitHub workflow during contributor docs refactoring. See https://github.com/gambitproject/gambit/issues/541 +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 @ for + +Refer to the `emoji key `__ for a list of contribution types. \ No newline at end of file