gdbgui/CONTRIBUTING.md

Thanks for your interest in contributing to gdbgui!

If your change is small, go ahead and submit a pull request. If it is substantial, create a GitHub issue to discuss it before making the change.

Dependencies

1.) nox is used to automate various tasks. You will need it installed on your system before continuing.

You can install it with pipx (recommended):

> pipx install nox

or pip:

> pip install --user nox

2.) yarn is used for managing JavaScript files

Developing

Development can be done with one simple step:

> nox -s develop

This will install all Python and JavaScript dependencies, and build and watch Python and JavaScript files for changes, automatically reloading as things are changed.

Make sure you turn your cache off so that changes made locally are reflected in the page.

Running and Adding tests

> nox

runs all applicable tests and linting.

Python tests are in gdbgui/tests. They are run as part of the above command, but can be run with

> nox -s python_tests

JavaScript tests are in gdbgui/src/js/tests. They are run as part of the above command, but can be run with

> nox -s js_tests

Documentation

Modifying Documentation

Documentation is made with mkdocs. Then make changes to mkdocs.yml or md files in the docs directory.

To build docs, run

nox -s docs

To see a live preview of current documentation, run

nox -s watch_docs

Publishing Documentation

The generated documentation is published to the gh-pages branch.

nox -s publish_docs

Building Binary Executables

These are automatically built on CI, but can be built locally with corresponding nox commands, such as:

nox -s build_executables_current_platform

Publishing a New Version

1. Make sure the version number is incremented in VERSION.txt.
2. The version to release must be on the master branch and have all CI tests pass and new binary executable artifacts attached to the GitHub action results
3. Publish the package to PyPI and update documentation. Both are done with this nox -s publish.
4. Create a "release" in GitHub and attach the gdbgui binary executable artifacts to it.