doc/source/coder.rst

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