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
  82
  83 test and demo walk-through
  84 --------------------------
  85
  86 The included tox configuration provides testenv definitions for a
  87 variety of analyzers, regression tests, documentation builds and
  88 package generation. It also has a ``demo`` testenv which will run the
  89 server using the provided :file:`etc/mudpy.conf` and other sample
  90 files. By default it listens on TCP port 4000 at the IPv6 loopback
  91 address, streams its logging to the terminal via stdout, and grants
  92 administrative rights automatically to an account named ``admin``
  93 (once created).
  94
  95 Because all the dependencies besides the ``python3`` interpreter itself
  96 are available from PyPI, installing them should be fairly similar
  97 across most GNU/Linux distributions. For example, on Debian 10 (a.k.a.
  98 "Buster") you need to expressly install the ``pip`` and ``venv`` modules
  99 since they're packaged separately from the rest of the Python standard
 100 library. Once that's done, you can perform local installs of ``tox`` and
 101 ``tox-venv`` as a normal non-root user. We're also going to install
 102 system packages for the ``git`` revision control toolset and an
 103 extensible console-based MUD client called ``tf5`` (TinyFugue version
 104 5)::
 105
 106     sudo apt install git python3-pip python3-venv tf5
 107     pip install --user tox tox-venv
 108     exit
 109
 110 The reason for exiting is that, if this is the first time you've ever
 111 used pip's ``--user`` option, when you log back in your ``~/.profile``
 112 should see that there's now a ``~/.local/bin`` directory and add it to
 113 your ``$PATH`` environment variable automatically from that point on.
 114 Next, retrieve the project source code and switch your current working
 115 directory to where you've cloned it::
 116
 117     git clone https://mudpy.org/code/mudpy
 118     cd mudpy
 119
 120 Now you should be able to invoke any tox testenv you like. Just
 121 running ``tox`` without any additional options will go through the
 122 defalt battery of checks and is a good way to make sure everything is
 123 installed and working. Once you're ready to try out the server
 124 interactively, launch it like this::
 125
 126     tox -e demo
 127
 128 Now in another terminal/session (because the one you've been using is
 129 busy displaying the server's logs) connect using a MUD client::
 130
 131     tf5 ip6-localhost 4000
 132
 133 Log in as ``admin`` creating an account and then an avatar and awaken
 134 it. Try out the ``help`` command and make sure you see some command
 135 words in red (you're using a color terminal, right?) since those are
 136 admin-only commands and being able to see them confirms you're an
 137 administrator. When you're ready to terminate the service you can
 138 either give the ``halt`` command in your MUD client terminal or press
 139 the ``control`` and ``c`` keys together in the terminal where you ran
 140 tox. To exit the MUD client, give it the ``/quit`` command.