From 11aedec4f45042d681e528a2f462bc588ab5adca Mon Sep 17 00:00:00 2001 From: Daniele Nicolodi Date: Fri, 31 Oct 2025 20:40:04 +0100 Subject: [PATCH] DOC: add contributing guide --- docs/how-to-guides/contributing.rst | 86 +++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 87 insertions(+) create mode 100644 docs/how-to-guides/contributing.rst diff --git a/docs/how-to-guides/contributing.rst b/docs/how-to-guides/contributing.rst new file mode 100644 index 000000000..a9fe5186c --- /dev/null +++ b/docs/how-to-guides/contributing.rst @@ -0,0 +1,86 @@ +.. SPDX-FileCopyrightText: 2021 The meson-python developers +.. +.. SPDX-License-Identifier: MIT + +.. _how-to-guides-contributing: + +Contributing +============ + +Thank you for your interest in contributing. ``meson-python`` development is +hosted on GitHub_ and uses the ubiquitous pull-request based workflow. The +usual Python development practices apply. Python source code should adhere to +the `PEP 8`_ code style with a maximum line length of 127 characters. Single +quotes are used as string delimiters. Python code uses type annotations +verified via Mypy_ and is kept clean linting it with Ruff_. + +``meson-python`` focus is producing Python wheels containing extension modules +and thus running its test suite requires C and C++ compilers, and CMake. The +``patchelf`` utility is required on Linux. These are best installed via the +system package manager. + +The documentation is written in reST format and the published version is +generated with Sphinx_. + +To work on the code: + +1. Fork the repository. + +2. Set up the development environment by creating a virtual environment and + installing the necessary dependencies for development and testing: + + .. code-block:: console + + $ uv venv + $ source .venv/bin/activate + $ uv pip install meson ninja pyproject-metadata + $ uv pip install --no-build-isolation --editable . + $ uv pip install --group test + $ uv pip install ruff mypy + +3. Create your branch from the ``main`` branch. + +4. Hack away. Add tests as necessary. + +5. Run the linter, the type checker, and the test suite: + + .. code-block:: console + + $ ruff check + $ mypy + $ pytest + +6. Organize your changes in logical commits with clear, concise, and well + formatted commit messages describing the motivation for the change. Commit + messages should be organized in a subject line, describing the commit + briefly, followed by a blank line, and more test if needed. Lines should be + word wrapped at 72 characters. + + The subject line should start with a capitalized acronym indicating the + nature of the commit, followed by a colon. Used acronyms include: "BUG" for + bug fixes, "ENH" for new features and other enhancements, "TST" for + addition or modification of tests, "MAINT" for maintenance commits, + typically refactoring, typo or code style fixes, "DOC" for documentation, + "CI" for changes to the continuous integration setup. + +To work on the documentation: + +1. Install the required tools: + + .. code-block:: console + + $ uv pip install --group docs + +2. Generate and inspect the HTML documentation: + + .. code-block:: console + + $ python -m sphinx docs html + $ open html/index.html + + +.. _GitHub: https://github.com/meson/meson-python/ +.. _Mypy: https://mypy.readthedocs.io +.. _PEP 8: https://www.python.org/dev/peps/pep-0008/ +.. _Ruff: https://docs.astral.sh/ruff/ +.. _Sphinx: https://www.sphinx-doc.org diff --git a/docs/index.rst b/docs/index.rst index f48e60e06..f56b7ebc0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -102,6 +102,7 @@ the use of ``meson-python`` and Meson for Python packaging. changelog about + how-to-guides/contributing Discussions Source Code Issue Tracker