doc/source/coder.rst

   1 =============
   2  coder guide
   3 =============
   4
   5 .. Copyright (c) 2004-2019 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`). The tox-venv_
  47 plug-in for tox is also recommended.
  48
  49 .. _tox: https://tox.readthedocs.io/
  50 .. _tox-venv: https://pypi.org/project/tox-venv/
  51
  52 application program interface
  53 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  54
  55 The :doc:`api` API documentation is maintained within docstrings in
  56 the mudpy source code.
  57
  58 regression testing
  59 ~~~~~~~~~~~~~~~~~~
  60
  61 All new commits are tested using a selftest script in the
  62 ``mudpy/tests`` directory of the source archive, to help ensure the
  63 software is continually usable. Any new features should be
  64 accompanied by suitable regression tests so that their functionality
  65 can be maintained properly through future releases. The selftest can
  66 be invoked with ``tox -e selftest`` after starting the daemon with
  67 the test configuration provided in the ``mudpy/tests/fixtures``
  68 directory.
  69
  70 style
  71 -----
  72
  73 This project follows Guido van Rossum and Barry Warsaw's `Style Guide`_
  74 for Python Code (a.k.a. "PEP-8"). When in need of sample code or other
  75 examples, any common source code file or text document file distributed
  76 as part of mudpy should serve as a suitable reference. Testing of all
  77 new patches with the flake8_ utility should be performed with ``tox
  78 -e flake8`` to ensure adherence to preferred style conventions.
  79
  80 .. _Style Guide: :pep:`0008`
  81 .. _flake8: https://pypi.org/project/flake8