From da5afa19ce2aef0ef4ecc68d7834d71fd8cce119 Mon Sep 17 00:00:00 2001 From: Kurt McKee Date: Fri, 27 Jun 2025 07:12:26 -0500 Subject: [PATCH] Move the `docs/contributing.rst` contents to `CONTRIBUTING.rst` This change makes it easier for people to contribute to the project when opening a PR. Currently, GitHub shows links to `CONTRIBUTING.rst` when opening a PR, but when people click on those links they are simply told "Go to a third-party website to view the contributing guidelines". This change replaces the manual redirect with actual content so that no third-party website (in this case, Read the Docs) is necessary to understand the contributing guidelines. In addition, `docs/contributing.rst` now uses a directive to `include` the contents of `CONTRIBUTING.rst`. This was tested by building the documentation locally and confirming that the HTML documentation still contained the contributing guidelines. The result is a streamlined contributing experience from within GitHub, no duplicated content, and no changes to the built documentation. --- CONTRIBUTING.rst | 77 ++++++++++++++++++++++++++++++++++++++++++- docs/contributing.rst | 77 +------------------------------------------ 2 files changed, 77 insertions(+), 77 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6f67057..ae9464f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1 +1,76 @@ -Please read the `Contributing `__ guidelines in the documentation site. +Contributing +============ + +Firstly, thank you all for taking the time to contribute. + +The following section describes how you can contribute to the openapi-spec-validator project on GitHub. + +Reporting bugs +-------------- + +Before you report +^^^^^^^^^^^^^^^^^ + +* Check whether your issue does not already exist in the `Issue tracker `__. +* Make sure it is not a support request or question better suited for `Discussion board `__. + +How to submit a report +^^^^^^^^^^^^^^^^^^^^^^ + +* Include clear title. +* Describe your runtime environment with exact versions you use. +* Describe the exact steps which reproduce the problem, including minimal code snippets. +* Describe the behavior you observed after following the steps, pasting console outputs. +* Describe expected behavior to see and why, including links to documentations. + +Code contribution +----------------- + +Prerequisites +^^^^^^^^^^^^^ + +Install `Poetry `__ by following the `official installation instructions `__. Optionally (but recommended), configure Poetry to create a virtual environment in a folder named ``.venv`` within the root directory of the project: + +.. code-block:: console + + poetry config virtualenvs.in-project true + +Setup +^^^^^ + +To create a development environment and install the runtime and development dependencies, run: + +.. code-block:: console + + poetry install + +Then enter the virtual environment created by Poetry: + +.. code-block:: console + + poetry shell + +Static checks +^^^^^^^^^^^^^ + +The project uses static checks using fantastic `pre-commit `__. Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then run following command to install pre-commit. + +To turn on pre-commit checks for commit operations in git, enter: + +.. code-block:: console + + pre-commit install + +To run all checks on your staged files, enter: + +.. code-block:: console + + pre-commit run + +To run all checks on all files, enter: + +.. code-block:: console + + pre-commit run --all-files + +Pre-commit check results are also attached to your PR through integration with Github Action. diff --git a/docs/contributing.rst b/docs/contributing.rst index ae9464f..b6e6c69 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,76 +1 @@ -Contributing -============ - -Firstly, thank you all for taking the time to contribute. - -The following section describes how you can contribute to the openapi-spec-validator project on GitHub. - -Reporting bugs --------------- - -Before you report -^^^^^^^^^^^^^^^^^ - -* Check whether your issue does not already exist in the `Issue tracker `__. -* Make sure it is not a support request or question better suited for `Discussion board `__. - -How to submit a report -^^^^^^^^^^^^^^^^^^^^^^ - -* Include clear title. -* Describe your runtime environment with exact versions you use. -* Describe the exact steps which reproduce the problem, including minimal code snippets. -* Describe the behavior you observed after following the steps, pasting console outputs. -* Describe expected behavior to see and why, including links to documentations. - -Code contribution ------------------ - -Prerequisites -^^^^^^^^^^^^^ - -Install `Poetry `__ by following the `official installation instructions `__. Optionally (but recommended), configure Poetry to create a virtual environment in a folder named ``.venv`` within the root directory of the project: - -.. code-block:: console - - poetry config virtualenvs.in-project true - -Setup -^^^^^ - -To create a development environment and install the runtime and development dependencies, run: - -.. code-block:: console - - poetry install - -Then enter the virtual environment created by Poetry: - -.. code-block:: console - - poetry shell - -Static checks -^^^^^^^^^^^^^ - -The project uses static checks using fantastic `pre-commit `__. Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then run following command to install pre-commit. - -To turn on pre-commit checks for commit operations in git, enter: - -.. code-block:: console - - pre-commit install - -To run all checks on your staged files, enter: - -.. code-block:: console - - pre-commit run - -To run all checks on all files, enter: - -.. code-block:: console - - pre-commit run --all-files - -Pre-commit check results are also attached to your PR through integration with Github Action. +.. include:: ../CONTRIBUTING.rst