Developer Guide¶
The developer’s guide is for a person who wants to change and contribute changes to mqtt-codec. It builds on information in User Guide.
Uncontrolled Builds¶
Uncontrolled source builds are created in the standard python fashion:
$ python setup.py sdist
running sdist
running egg_info
writing requirements to mqtt_codec.egg-info/requires.txt
writing mqtt_codec.egg-info/PKG-INFO
writing top-level names to mqtt_codec.egg-info/top_level.txt
writing dependency_links to mqtt_codec.egg-info/dependency_links.txt
reading manifest file 'mqtt_codec.egg-info/SOURCES.txt'
writing manifest file 'mqtt_codec.egg-info/SOURCES.txt'
running check
creating mqtt-codec-0.1.0-uncontrolled-20180907
creating mqtt-codec-0.1.0-uncontrolled-20180907/mqtt_codec
creating mqtt-codec-0.1.0-uncontrolled-20180907/mqtt_codec.egg-info
[... removed for brevity ...]
copying tests/test_reactor.py -> mqtt-codec-0.1.0-uncontrolled-20180907/tests
copying tests/test_scheduler.py -> mqtt-codec-0.1.0-uncontrolled-20180907/tests
Writing mqtt-codec-0.1.0-uncontrolled-20180907/setup.cfg
creating dist
Creating tar archive
removing 'mqtt-codec-0.1.0-uncontrolled-20180907' (and everything under it)
$ ls dist
mqtt-codec-0.1.0-uncontrolled-20180907.tar.gz
$
The output artifact has the word “uncontrolled” along with a build date so that users will know the artifact is not a release or from a continuous integration build server.
Tests¶
The mqtt-codec library comes with a battery of tests.
The built-in automated tests can be run from the command-line
using setup.py.
$ python setup.py test
$
Coverage¶
Test coverage is monitored using coverage.py version 4.5 or higher. Normally this can be installed through your operating system’s package manager (like rpm or apt-get) or by using pip. A coverage configuration file is included at .coveragerc and the tool can be run in this fashion:
$ coverage run setup.py test
running test
running egg_info
writing requirements to mqtt_codec.egg-info/requires.txt
writing mqtt_codec.egg-info/PKG-INFO
writing top-level names to mqtt_codec.egg-info/top_level.txt
writing dependency_links to mqtt_codec.egg-info/dependency_links.txt
reading manifest file 'mqtt_codec.egg-info/SOURCES.txt'
writing manifest file 'mqtt_codec.egg-info/SOURCES.txt'
running build_ext
test_read_after_close (tests.test_io.TestBytesReader) ... ok
test_body_underflow (tests.test_io.TestDecodeBytes) ... ok
[... removed for brevity...]
test_subscribe (tests.test_mqtt.TestUnsubscribe) ... ok
test_decode_encode (tests.test_mqtt.TestUtf8Codec) ... ok
test_encode_max_len_utf8 (tests.test_mqtt.TestUtf8Codec) ... ok
test_encode_too_long_utf8 (tests.test_mqtt.TestUtf8Codec) ... ok
----------------------------------------------------------------------
Ran 48 tests in 0.014s
OK
$ coverage report
Name Stmts Miss Branch BrPart Cover
----------------------------------------------------------
mqtt_codec/__init__.py 0 0 0 0 100%
mqtt_codec/io.py 162 4 32 1 97%
mqtt_codec/packet.py 587 40 110 27 89%
----------------------------------------------------------
TOTAL 749 44 142 28 91%
Docstrings¶
Python source code is documented according to the the numpy documentation standard at https://numpydoc.readthedocs.io/en/latest/format.html.
Documentation¶
The documentation for mqtt-codec is created with
Sphinx and is build the fashion usual to
that framework:
$ cd doc
$ make html
$
The documentation contains doctests which can be verified in this fashion:
$ make doctest
Running Sphinx v1.7.7
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [doctest]: targets for 5 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] user_guide
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
running tests...
Document: user_guide
--------------------
1 items passed all tests:
14 tests in default
14 tests in 1 items.
14 passed and 0 failed.
Test passed.
Doctest summary
===============
14 tests
0 failures in tests
0 failures in setup code
0 failures in cleanup code
build succeeded.
Testing of doctests in the sources finished, look at the results in build/doctest/output.txt.
As suggested by the text, the output can be found in build/doctest/output.txt.
Contributing Changes¶
If you have an idea for an enhancement then you are welcome to fork the github repository at https://github.com/kcallin/mqtt-codec, make your changes, and then submit a pull request.
Minimally, your git commit record must have the following:
- Your name and e-mail address captured in the “Author” field.
- A single line summary in the message field followed by a more detailed description.
- A “Signed-off-by” entry with matching credentials in the message footer.
If the commit fixes a bug then a link should be included in the message footer. The id (bug number) of the bug should also be included in the message summary.
You can specify additional authors using one or more “Also-by” entries in the message footer.
For example:
commit 862e6ff22ad56c10df6de3385ffa4c7d02363d1d
Author: Joe Somebody <somebody@someplace.net>
Date: Mon Jun 17 17:19:38 2013 -0700
[2] MqttPublish.payload must be bytes
The MqttPublish payload parameter is stored and returned by
MqttPublish.payload without checking that it is bytes. This
change adds an assertion that the payload parameter is bytes.
Bug: https://github.com/kcallin/mqtt-codec/issues/3
Also-by: Some Otherperson <otherperson@someplace.net>
Signed-off-by: Joe Somebody <somebody@someplace.net>
The “Signed-off-by” entry is required. By including this, you confirm that you are in compliance with the Certificate of Origin.
Note that the footer entries must occur at the bottom of the commit message and must not include any blank lines.
Signing off on a Commit¶
Git contains built-in support for signing off on a commit.
From command-line git, add -s to the command:
$ git commit -s --gpg-sign[=<keyid>] -m "[2] MqttPublish.payload must be bytes"