From ca233c0d45aaa753ce4d9c0513738c38cb43299e Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Tue, 16 Sep 2025 13:08:55 -0400 Subject: [PATCH] INTPYTHON-737 Document contributing guidelines --- docs/conf.py | 1 + docs/contents.rst | 2 +- docs/index.rst | 4 +- docs/internals/bugs-and-features.rst | 25 ++++ docs/internals/contributing/coding-style.rst | 35 ++++++ docs/internals/contributing/index.rst | 12 ++ docs/internals/contributing/unit-tests.rst | 88 ++++++++++++++ .../contributing/writing-documentation.rst | 107 ++++++++++++++++++ docs/internals/deprecation.rst | 6 + docs/internals/index.rst | 16 +++ .../release-process.rst} | 28 +---- docs/internals/security.rst | 12 ++ 12 files changed, 308 insertions(+), 28 deletions(-) create mode 100644 docs/internals/bugs-and-features.rst create mode 100644 docs/internals/contributing/coding-style.rst create mode 100644 docs/internals/contributing/index.rst create mode 100644 docs/internals/contributing/unit-tests.rst create mode 100644 docs/internals/contributing/writing-documentation.rst create mode 100644 docs/internals/deprecation.rst create mode 100644 docs/internals/index.rst rename docs/{internals.rst => internals/release-process.rst} (66%) create mode 100644 docs/internals/security.rst diff --git a/docs/conf.py b/docs/conf.py index 09dc4ebeb..dfe3a3289 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,6 +51,7 @@ "python": ("https://docs.python.org/3/", None), "atlas": ("https://www.mongodb.com/docs/atlas/", None), "manual": ("https://www.mongodb.com/docs/manual/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master", None), } # -- Options for HTML output ------------------------------------------------- diff --git a/docs/contents.rst b/docs/contents.rst index 2def4b8a9..4b468a530 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -15,7 +15,7 @@ Table of contents howto/index faq releases/index - internals + internals/index Indices ======= diff --git a/docs/index.rst b/docs/index.rst index 642614446..50e35f539 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,7 +61,7 @@ Miscellaneous ============= - :doc:`releases/index` -- :doc:`internals` +- :doc:`internals/index` .. Keep this toctree in sync with contents.rst. @@ -75,4 +75,4 @@ Miscellaneous howto/index faq releases/index - internals + internals/index diff --git a/docs/internals/bugs-and-features.rst b/docs/internals/bugs-and-features.rst new file mode 100644 index 000000000..5fbd230d0 --- /dev/null +++ b/docs/internals/bugs-and-features.rst @@ -0,0 +1,25 @@ +====================================== +Reporting bugs and requesting features +====================================== + +.. Important:: + + Please :ref:`report security issues privately `. + +.. _issue-tracker: + +Issue tracker +============= + +To report a bug or request a new feature in Django MongoDB Backend, please open +an issue in our issue tracker, JIRA: + +1. Create a `JIRA account `_. + +2. Navigate to the `Python Integrations project + `_. + +3. Click **Create Issue**. Please provide as much information as possible about + the issue and the steps to reproduce it. + +Bug reports in JIRA for this project can be viewed by everyone. diff --git a/docs/internals/contributing/coding-style.rst b/docs/internals/contributing/coding-style.rst new file mode 100644 index 000000000..8f7d09c6b --- /dev/null +++ b/docs/internals/contributing/coding-style.rst @@ -0,0 +1,35 @@ +============ +Coding style +============ + +Please follow these coding standards when writing code. + +.. _coding-style-pre-commit: + +Pre-commit checks +================= + +`pre-commit `_ is a framework for managing pre-commit +hooks. These hooks help to identify simple issues before committing code for +review. By checking for these issues before code review it allows the reviewer +to focus on the change itself, and it can also help to reduce the number of CI +runs. + +To use the tool, first install ``pre-commit`` and then the git hooks: + +.. code-block:: bash + + $ python -m pip install pre-commit + $ pre-commit install + +On the first commit ``pre-commit`` will install the hooks, these are installed +in their own environments and will take a short while to install on the first +run. Subsequent checks will be significantly faster. If an error is found an +appropriate error message will be displayed. If the error was with ``ruff`` (a +tool to standardize code formatting), then it will go ahead and fix it for you. +Review the changes and re-stage for commit if you are happy with them. + +.. seealso:: + + The guidelines from Django's :ref:`Python style guide` + are generally applicable. diff --git a/docs/internals/contributing/index.rst b/docs/internals/contributing/index.rst new file mode 100644 index 000000000..c596c1953 --- /dev/null +++ b/docs/internals/contributing/index.rst @@ -0,0 +1,12 @@ +================= +Contributing code +================= + +So you'd like to write some code or documentation to improve Django MongoDB +Backend? Here are some resources: + +.. toctree:: + + coding-style + unit-tests + writing-documentation diff --git a/docs/internals/contributing/unit-tests.rst b/docs/internals/contributing/unit-tests.rst new file mode 100644 index 000000000..2144e705b --- /dev/null +++ b/docs/internals/contributing/unit-tests.rst @@ -0,0 +1,88 @@ +========== +Unit tests +========== + +Django MongoDB Backend uses the Django test suite, located in +``django-repo/tests``, as well as additional tests of its own, located in the +``tests`` directory of the Django MongoDB Backend repository. + +The tests use the testing infrastructure that ships with Django. See +:doc:`django:topics/testing/overview` for an explanation of how to write new +tests. + +.. _running-unit-tests: + +Running the unit tests +====================== + +First, `fork Django MongoDB Backend on GitHub +`__. + +Second, create and activate a Python virtual environment: + +.. code-block:: bash + + $ python -m venv .venv + $ source .venv/bin/activate + +Third, clone your fork and install it: + +.. code-block:: bash + + $ git clone https://github.com/YourGitHubName/django-mongodb-backend.git + $ cd django-mongodb-backend + $ pip install -e . + +Next, get and install a copy of MongoDB's Django fork. This fork has some +test suite adaptions for Django MongoDB Backend. There is a branch for each +feature release of Django (e.g. ``mongodb-5.2.x`` below). + +.. code-block:: bash + + $ git clone https://github.com/mongodb-forks/django.git django-repo + $ cd django-repo + $ git checkout -t origin/mongodb-5.2.x + $ python -m pip install -e . + $ python -m pip install -r tests/requirements/py3.txt + +Next, start :doc:`a local instance of mongod +`. + +Then, create a test settings file, ``django-repo/tests/test_mongo.py``:: + + from test_sqlite import * + + DATABASES = { + "default": { + "ENGINE": "django_mongodb_backend", + "NAME": "django", + # Needed if connecting to the Atlas test VM. + "OPTIONS": {"directConnection": True}, + }, + "other": { + "ENGINE": "django_mongodb_backend", + "NAME": "django1", + "OPTIONS": {"directConnection": True}, + }, + } + + DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField" + +Finally, you can run the test script in the Django repository: + + $ ./tests/runtests.py --settings=test_mongo basic + +This runs the tests in ``django-repo/tests/basic``. You can also specify a +directory in ``django-mongodb-backend/tests``. All of these directories +have an underscore suffix (e.g. ``queries_``) to distinguish them from Django's +own test directories. + +.. warning:: + + Don't try to invoke ``runtests.py`` without specifying any test apps + (directories) as running all the tests at once will take hours. + +.. seealso:: + + :doc:`Django's guide to running its test suite + `. diff --git a/docs/internals/contributing/writing-documentation.rst b/docs/internals/contributing/writing-documentation.rst new file mode 100644 index 000000000..2eae442a1 --- /dev/null +++ b/docs/internals/contributing/writing-documentation.rst @@ -0,0 +1,107 @@ +===================== +Writing documentation +===================== + +The documentation uses the `Sphinx `_ +documentation system. + +How the documentation is organized +================================== + +The documentation is organized into several categories: + +* :doc:`Tutorials ` take the reader by the hand through a series + of steps to create something. + + The important thing in a tutorial is to help the reader achieve something + useful, preferably as early as possible, in order to give them confidence. + + Explain the nature of the problem we're solving, so that the reader + understands what we're trying to achieve. Don't feel that you need to begin + with explanations of how things work - what matters is what the reader does, + not what you explain. It can be helpful to refer back to what you've done and + explain afterward. + +* :doc:`Topic guides ` aim to explain a concept or subject at a + fairly high level. + + Link to reference material rather than repeat it. Use examples and don't be + reluctant to explain things that seem very basic to you - it might be the + explanation someone else needs. + + Providing background context helps a newcomer connect the topic to things + that they already know. + +* :doc:`Reference guides ` contain technical references for APIs. + They describe the functioning of Django MongoDB Backend's internal machinery + and instruct in its use. + + Keep reference material tightly focused on the subject. Assume that the + reader already understands the basic concepts involved but needs to know or + be reminded of how Django MongoDB Backend does it. + + Reference guides aren't the place for general explanation. If you find + yourself explaining basic concepts, you may want to move that material to a + topic guide. + +* :doc:`How-to guides ` are recipes that take the reader through + steps in key subjects. + + What matters most in a how-to guide is what a user wants to achieve. + A how-to should always be result-oriented rather than focused on internal + details of how Django MongoDB Backend implements whatever is being discussed. + + These guides are more advanced than tutorials and assume some knowledge about + how Django MongoDB Backendo works. + +How to start contributing documentation +======================================= + +Clone the Django repository to your local machine +------------------------------------------------- + +If you'd like to start contributing to the docs, get the source code +repository: + +.. code-block:: bash + + $ git clone https://github.com/mongodb/django-mongodb-backend.git + +If you're planning to submit these changes, you might find it useful to make a +fork of this repository and clone your fork instead. + +Set up a virtual environment and install dependencies +----------------------------------------------------- + +Create and activate a virtual environment, then install the dependencies: + +.. code-block:: bash + + $ python -m venv .venv + $ source .venv/bin/activate + $ python -m pip install -e ".[docs]" + +Build the documentation locally +------------------------------- + +You build the HTML output from the ``docs`` directory: + +.. code-block:: bash + + $ cd docs + $ make html + +Your locally-built documentation will be accessible at +``_build/html/index.html`` and it can be viewed in any web browser. + +Making edits to the documentation +--------------------------------- + +The source files are ``.rst`` files located in the ``docs/`` directory. + +These files are written in the reStructuredText markup language. To learn the +markup, see the :ref:`reStructuredText reference `. + +To edit this page, for example, edit the file +``docs/internals/contributing/writing-documentation.txt`` and rebuild the +HTML with ``make html``. diff --git a/docs/internals/deprecation.rst b/docs/internals/deprecation.rst new file mode 100644 index 000000000..84d53c1c6 --- /dev/null +++ b/docs/internals/deprecation.rst @@ -0,0 +1,6 @@ +==================== +Deprecation Timeline +==================== + +This document outlines when various pieces of Django MongoDB Backend will be +removed or altered in a backward incompatible way, following their deprecation. diff --git a/docs/internals/index.rst b/docs/internals/index.rst new file mode 100644 index 000000000..cdac56ac0 --- /dev/null +++ b/docs/internals/index.rst @@ -0,0 +1,16 @@ +================= +Project internals +================= + +Documentation for people working on Django MongoDB Backend itself. This is the +place to go if you'd like to help improve Django MongoDB Backend or learn about +how the project is managed. + +.. toctree:: + :maxdepth: 2 + + bugs-and-features + contributing/index + security + release-process + deprecation diff --git a/docs/internals.rst b/docs/internals/release-process.rst similarity index 66% rename from docs/internals.rst rename to docs/internals/release-process.rst index 314c16dd1..09f560217 100644 --- a/docs/internals.rst +++ b/docs/internals/release-process.rst @@ -1,28 +1,6 @@ -================= -Project internals -================= - -Documentation for people working on Django MongoDB Backend itself. This is the -place to go if you'd like to help improve Django MongoDB Backend or learn about -how the project is managed. - -.. _issue-tracker: - -Issue tracker -============= - -To report a bug or to request a new feature in Django MongoDB Backend, please -open an issue in our issue tracker, JIRA: - -1. Create a `JIRA account `_. - -2. Navigate to the `Python Integrations project - `_. - -3. Click **Create Issue**. Please provide as much information as possible about - the issue and the steps to reproduce it. - -Bug reports in JIRA for this project can be viewed by everyone. +=============== +Release process +=============== .. _supported-versions-policy: diff --git a/docs/internals/security.rst b/docs/internals/security.rst new file mode 100644 index 000000000..9291c9b88 --- /dev/null +++ b/docs/internals/security.rst @@ -0,0 +1,12 @@ +================= +Security policies +================= + +.. _reporting-security-issues: + +Reporting security issues +========================= + +If you identify a security vulnerability in this project or in any other +MongoDB project, please report it according to the instructions found at +:doc:`manual:tutorial/create-a-vulnerability-report`.