Fix file pathing in daemon mode
[mudpy.git] / 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