doc/source/coder.rst

   1 =============
   2  coder guide
   3 =============
   4
   5 .. Copyright (c) 2004-2018 Jeremy Stanley <fungi@yuggoth.org>.
   6    Permission to use, copy, modify, and distribute this software is
   7    granted under terms provided in the LICENSE file distributed with
   8    this software.
   9
  10 This guide attempts to embody a rudimentary set of rules for developer
  11 submissions of source code and documentation targeted for inclusion
  12 within the mudpy project, as well as pointers to useful resources for
  13 those attempting to obtain a greater understanding of the software.
  14
  15 source
  16 ------
  17
  18 As with any project, the mudpy source code could always be better
  19 documented, and contributions to that end are heartily welcomed.
  20
  21 version control system
  22 ~~~~~~~~~~~~~~~~~~~~~~
  23
  24 Git_ is used for version control on the project, and the archive can
  25 be browsed or cloned anonymously from https://mudpy.org/code/mudpy .
  26 For now, detailed commits can be E-mailed to fungi@yuggoth.org, but
  27 there will most likely be a developer mailing list for more open
  28 presentation and discussion of patches soon.
  29
  30 A :file:`ChangeLog` is generated automatically from repository
  31 commit logs, and is included automatically in all sdist_ tarballs. It
  32 can be regenerated easily by running :command:`tox -e venv python
  33 setup.py sdist` from the top level directory of the Git repository in
  34 a working `developer environment`_.
  35
  36 .. _Git: https://git-scm.com/
  37 .. _sdist: https://packaging.python.org/glossary
  38            /#term-source-distribution-or-sdist
  39
  40 developer environment
  41 ~~~~~~~~~~~~~~~~~~~~~
  42
  43 Basic developer requirements are a POSIX Unix derivative (such as
  44 Linux), a modern Python 3 interpreter (any of the minor revisions
  45 mentioned in the ``metadata.classifier`` section of
  46 :file:`setup.cfg`) and a recent release of the tox_ utility (at least
  47 the ``tox.minversion`` mentioned in :file:`tox.ini`).
  48
  49 .. _tox: https://tox.readthedocs.io/
  50
  51 application program interface
  52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 API documentation is maintained within docstrings in the mudpy source
  55 code.
  56
  57 regression testing
  58 ~~~~~~~~~~~~~~~~~~
  59
  60 All new commits are tested using a selftest script in the
  61 ``mudpy/tests`` directory of the source archive, to help ensure the
  62 software is continually usable. Any new features should be
  63 accompanied by suitable regression tests so that their functionality
  64 can be maintained properly through future releases. The selftest can
  65 be invoked with ``tox -e selftest`` after starting the daemon with
  66 the test configuration provided in the ``mudpy/tests/fixtures``
  67 directory.
  68
  69 style
  70 -----
  71
  72 This project follows Guido van Rossum and Barry Warsaw's `Style Guide`_
  73 for Python Code (a.k.a. "PEP-8"). When in need of sample code or other
  74 examples, any common source code file or text document file distributed
  75 as part of mudpy should serve as a suitable reference. Testing of all
  76 new patches with the flake8_ utility should be performed with ``tox
  77 -e flake8`` to ensure adherence to preferred style conventions.
  78
  79 .. _Style Guide: :pep:`0008`
  80 .. _flake8: https://pypi.org/project/flake8