Initial pages.

chevah · Jul 7, 2022 · b857164 · b857164
1 parent f2c675a
commit b857164
Show file tree

Hide file tree

Showing 7 changed files with 418 additions and 296 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -9,19 +9,17 @@ Twisted has a [Code of Conduct](./code_of_conduct.md).
 Examples of contributions include:
 
 * Code patches
-* Documentation improvements
+* Documentation improvements, as small as typo fixes
 * Bug reports
 * Pull request reviews
 
+Bug reports or feature requests are managed using GitHub Issues.
+
 Contributions are managed using GitHub's Pull Requests.
 For a PR to be accepted:
 
-* It must have an associated Trac ticket ([file one here](https://twistedmatrix.com/trac/newticket))
+* It must have an associated GitHub issue ([file one here](https://github.com/twisted/twisted/issues/new/choose))
 * All automated checks must pass
 * The changeset must have 100% patch test coverage
 
-Twisted uses Trac to keep track of bugs, feature requests, and associated
-patches because GitHub doesn't provide adequate tooling for its community.
-You can log in to Trac with your GitHub account.
-
-Extensive contribution guidelines are [available online](https://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs).
+Extensive contribution guidelines are [available online](https://docs.twisted.org/en/latest/core/development/dev-process.html)
diff --git a/docs/core/development/dev-process.rst b/docs/core/development/dev-process.rst
@@ -0,0 +1,153 @@
+Development process
+===================
+
+This page described the process that should be followed for contributing to Twisted.
+
+
+If you're going to be doing development on Twisted itself,
+or if you want to take advantage of bleeding-edge features (or bug fixes) that are not yet available in a numbered release,
+you'll probably want to check out a tree from the Twisted Git repository.
+
+The `trunk` is the main branch and is where all current development takes place.
+
+
+
+Checkout and initial dev virtual environment
+--------------------------------------------
+
+
+Git tutorials can be found elsewhere, see in particular `Git and GitHub learning resources <https://help.github.com/articles/good-resources-for-learning-git-and-github/>`_ :
+
+.. code-block:: console
+
+    $ git clone https://github.com/twisted/twisted twisted
+    $ virtualenv venv
+    $ . venv/bin/activate
+    $ pip install -e .[dev]
+    $ pip install pre-commit
+
+The output of ``git blame`` `will be better <https://github.com/psf/black#migrating-your-code-style-without-ruining-git-blame>`_ if you configure it to use our ignore file:
+
+.. code-block:: console
+
+    $ cd twisted
+    $ git config blame.ignoreRevsFile .git-blame-ignore-revs
+
+
+Running tests
+-------------
+
+The test are handled by `trial` testing framework.
+It knows about deferred and any other good stuff provided by Twisted.
+To run the full unit-test suite, do:
+
+.. code-block:: console
+
+    ./bin/trial twisted
+
+
+To run a single test file (like ``twisted/test/test_defer.py`` ), do one of:
+
+.. code-block:: console
+
+    ./bin/trial twisted.test.test_defer
+    # or
+    ./bin/trial twisted/test/test_defer.py
+
+
+
+To run any tests that are related to a code file, like ``twisted/protocols/imap4.py`` , do:
+
+.. code-block:: console
+
+    ./bin/trial --testmodule twisted/mail/imap4.py
+
+
+This depends upon the ``.py`` file having an appropriate "test-case-name" tag that indicates which test cases provide coverage.
+See the :doc:`Test Standards <policy/test-standard>` document for
+details about using "test-case-name".
+In this example, the ``twisted.mail.test.test_imap`` test will be run.
+
+Many tests create temporary files in /tmp or ./_trial_temp,
+but everything in /tmp should be deleted when the test finishes.
+Sometimes these cleanup calls are commented out by mistake, so if you see a stray ``/tmp/@12345.1`` directory, it is probably from ``test_dirdbm`` or ``test_popsicle`` .
+Look for an ``rmtree`` that has been commented out and complain to the last developer who touched that file.
+
+
+Building docs
+-------------
+
+Twisted documentation is generated by `Sphinx <https://sphinx-doc.org/>`_.
+The automatically-generated API docs is generated by `pydoctor <https://pydoctor.readthedocs.io/>`_.
+
+To build the HTML form of the docs into the ``doc/`` directory, do the following.
+This will trigger a full build including the API docs:
+
+.. code-block:: console
+
+    tox -e narrativedocs
+    firefox docs/_build/index.html
+
+
+Committing and Post-commit Hooks
+--------------------------------
+
+
+Twisted's Trac installation is notified when the Git repository changes,
+and will update the ticket depending on the Git commit logs.
+When making a branch for a ticket, the branch name should end
+in ``-<ticket number>`` , for
+example ``my-branch-9999`` . This will add a ticket comment containing a
+changeset link and branch name. To make your commit message show up as a comment
+on a Trac ticket, add a ``refs #<ticket number>`` line at the
+bottom of your commit message. To automatically close a ticket on Trac
+as ``Fixed`` and add a comment with the closing commit message, add
+a ``Fixes: #<ticket number>`` line to your commit message. In
+general, a commit message closing a ticket looks like this:
+
+
+
+
+
+::
+
+    
+    Merge my-branch-9999: A single-line summary.
+    
+    Author: jesstess
+    Reviewers: exarkun, glyph
+    Fixes: #9999
+    
+    My longer description of the changes made.
+
+
+
+
+The :doc:`Twisted Coding Standard <coding-standard>` 
+elaborates on commit messages and source control.
+
+
+
+
+
+Emacs
+-----
+
+
+
+A minor mode for development with Twisted using Emacs is available.  See ``twisted-dev.el`` , provided by `twisted-emacs <https://launchpad.net/twisted-emacs>`_ ,
+for several utility functions which make it easier to grep for methods, run test cases, etc.
+
+
+
+
+
+Building Debian packages
+------------------------
+
+
+
+Our support for building Debian packages has fallen into disrepair.  We
+would very much like to restore this functionality, but until we do so, if
+you are interested in this, you are on your own.  See `stdeb <https://github.com/astraw/stdeb>`_ for one possible approach to
+this.
diff --git a/docs/core/development/index.rst b/docs/core/development/index.rst
@@ -1,21 +1,13 @@
-
-:LastChangedDate: $LastChangedDate$
-:LastChangedRevision: $LastChangedRevision$
-:LastChangedBy: $LastChangedBy$
-
 Development of Twisted
 ======================
 
+This section of documentation is for people who work on the Twisted codebase itself,
+rather than for people who want to use Twisted in their projects.
+
 .. toctree::
-   :hidden:
 
+   dev-process
+   review-process
    naming
    philosophy
    policy/index
-
-
-This documentation is for people who work on the Twisted codebase itself, rather than for people who want to use Twisted in their own projects.
-
-- :doc:`Naming <naming>`
-- :doc:`Philosophy <philosophy>`
-- :doc:`Twisted development policy <policy/index>`