doc/source/coder.rst

   1 =============
   2  coder guide
   3 =============
   4
   5 :Copyright: (c) 2004-2017 Jeremy Stanley <fungi@yuggoth.org>. Permission
   6             to use, copy, modify, and distribute this software is
   7             granted under terms provided in the LICENSE file distributed
   8             with 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 .. sectnum:: :prefix: 1.
  16 .. contents:: :local:
  17
  18 --------
  19  source
  20 --------
  21
  22 As with any project, the mudpy source code could always be better
  23 documented, and contributions to that end are heartily welcomed.
  24
  25 version control system
  26 ----------------------
  27
  28 Git_ is used for version control on the project, and the archive can be
  29 cloned anonymously from http://mudpy.org/git/mudpy if desired. For now,
  30 detailed commits can be E-mailed to fungi@yuggoth.org, but there will
  31 most likely be a developer mailing list for more open presentation and
  32 discussion of patches soon.
  33
  34 A Gitweb_ interface is available, to make the change history easier to
  35 browse. This is found at http://mudpy.org/gitweb/mudpy/ and should be
  36 fairly self-explanatory.
  37
  38 A ChangeLog file is generated automatically from repository commit
  39 logs, and is included automatically in all sdist_ tarballs. It can
  40 be regenerated easily by running `tox -e venv python setup.py sdist`
  41 from the top level directory of the Git repository in a working
  42 `developer environment`_.
  43
  44 .. _Git: http://git-scm.com/
  45 .. _Gitweb: http://git.wiki.kernel.org/index.php/Gitweb
  46 .. _sdist: https://packaging.python.org/glossary
  47            /#term-source-distribution-or-sdist
  48
  49 developer environment
  50 ---------------------
  51
  52 Basic developer requirements are a POSIX Unix derivative (such as
  53 Linux), a modern Python 3 interpreter (any of the minor revisions
  54 mentioned in the ``metadata.classifier`` section of setup.cfg_) and
  55 a recent release of the tox_ utility (at least the
  56 ``tox.minversion`` mentioned in tox.ini_).
  57
  58 .. _setup.cfg: http://mudpy.org/gitweb?p=mudpy.git;a=blob;f=setup.cfg
  59 .. _tox.ini: http://mudpy.org/gitweb?p=mudpy.git;a=blob;f=tox.ini
  60
  61 application program interface
  62 -----------------------------
  63
  64 API documentation is maintained within docstrings in the mudpy source
  65 code.
  66
  67 regression testing
  68 ------------------
  69
  70 All new commits are tested using a selftest script in the
  71 ``mudpy/tests`` directory of the source archive, to help ensure the
  72 software is continually usable. Any new features should be
  73 accompanied by suitable regression tests so that their functionality
  74 can be maintained properly through future releases. The selftest can
  75 be invoked with ``tox -e selftest`` after starting the daemon with
  76 the test configuration provided in the ``mudpy/tests/fixtures``
  77 directory.
  78
  79 -------
  80  style
  81 -------
  82
  83 This project follows Guido van Rossum and Barry Warsaw's `Style Guide`_
  84 for Python Code (a.k.a. "PEP-8"). When in need of sample code or other
  85 examples, any common source code file or text document file distributed
  86 as part of mudpy should serve as a suitable reference. Testing of all
  87 new patches with the flake8_ utility should be performed with ``tox
  88 -e flake8`` to ensure adherence to preferred style conventions.
  89
  90 .. _Style Guide: http://www.python.org/dev/peps/pep-0008/
  91 .. _flake8: https://pypi.python.org/pypi/flake8