INTPYTHON-737 Document contributing guidelines

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 -------------------------------------------------

docs/contents.rst

@@ -15,7 +15,7 @@ Table of contents
     howto/index
     faq
     releases/index
-    internals
+    internals/index
 
 Indices
 =======

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

docs/internals/bugs-and-features.rst

@@ -0,0 +1,25 @@
+======================================
+Reporting bugs and requesting features
+======================================
+
+.. Important::
+
+    Please :ref:`report security issues privately <reporting-security-issues>`.
+
+.. _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 <https://jira.mongodb.org/>`_.
+
+2. Navigate to the `Python Integrations project
+   <https://jira.mongodb.org/projects/INTPYTHON/>`_.
+
+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.

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 <https://pre-commit.com>`_ 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<coding-style-python>`
+    are generally applicable.

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

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
+<https://github.com/mongodb/django-mongodb-backend/fork>`__.
+
+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
+<manual:tutorial/manage-mongodb-processes>`.
+
+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
+    <django:internals/contributing/writing-code/unit-tests>`.

docs/internals/contributing/writing-documentation.rst

@@ -0,0 +1,107 @@
+=====================
+Writing documentation
+=====================
+
+The documentation uses the `Sphinx <https://www.sphinx-doc.org/>`_
+documentation system.
+
+How the documentation is organized
+==================================
+
+The documentation is organized into several categories:
+
+* :doc:`Tutorials </intro/index>` 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 </topics/index>` 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 </ref/index>` 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 </howto/index>` 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 <sphinx:rst-index>`.
+
+To edit this page, for example, edit the file
+``docs/internals/contributing/writing-documentation.txt`` and rebuild the
+HTML with ``make html``.

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.

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

docs/internals.rst → 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 <https://jira.mongodb.org/>`_.
-
-2. Navigate to the `Python Integrations project
-   <https://jira.mongodb.org/projects/INTPYTHON/>`_.
-
-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:
 

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`.