circup/CONTRIBUTING.rst

Contributing
============

Please note that this project is released with a Contributor Code of Conduct.
By participating in this project you agree to abide by its terms. Participation
covers any forum used to converse about CircuitPython including unofficial and
official spaces. Failure to do so will result in corrective actions such as
time out or ban from the project.

Licensing
---------

By contributing to this repository you are certifying that you have all
necessary permissions to license the code under an MIT License. You still
retain the copyright but are granting many permissions under the MIT License.

If you have an employment contract with your employer please make sure that
they don't automatically own your work product. Make sure to get any necessary
approvals before contributing. Another term for this contribution off-hours is
moonlighting.


Developer Setup
---------------

.. note::

    Please try to use Python 3.6+ while developing CircUp. This is so we can
    use the
    `Black code formatter <https://black.readthedocs.io/en/stable/index.html>`_
    (which only works with Python 3.6+).



Clone the repository and from the root of the project,


setup a virtual environment and activate it.::

    python3 -m venv .env
    source .env/bin/activate

install the requirements::

    pip install -e ".[dev]"


.. note::
    This repository provides a `devcontainer` environment that can be used in VSCode. For more information, read `VSCode containers docs <https://code.visualstudio.com/docs/devcontainers/containers>`_.
    This provides a ready to use development environment when you launch VSCode in the devcontainer.


Run the test suite::

    pytest --random-order --cov-config .coveragerc --cov-report term-missing --cov=circup


How Does Circup Work?
#####################

The ``circup`` tool checks for a connected CircuitPython device by
interrogating the local filesystem to find a path to a directory which ends
with ``"CIRCUITPYTHON"`` (the name under which a CircuitPython device is
mounted by the host operating system). This is handled in the ``find_device``
function.

A Python module on a connected device is represented by an instance of the
``Module`` class. This class provides useful methods for discerning if the
module is out of date, returning useful representations of it in order to
display information to the user, or updating the module on the connected
device with whatever the version is in the latest Adafruit CircuitPython
Bundle.

All of the libraries included in the Adafruit CircuitPython Bundle contain,
somewhere within their code, two metadata objects called ``__version__`` and
``__repo__``.

The ``__repo__`` object is a string containing the GitHub repository URL, as
used to clone the project.

The ``__version__`` object is interesting because *within the source code in
Git* the value is **always** the string ``"0.0.0-auto.0"``. When a new release
is made of the bundle, this value is automatically replaced by the build
scripts to the correct version information, which will always conform to the
`semver standard <https://semver.org/>`_.

Given this context, the ``circup`` tool will check a configuration file
to discern what *it* thinks is the latest version of the bundle. If there is
no configuration file (for example, on first run), then the bundle version is
assumed to be ``"0"``.

Next, it checks GitHub for the tag value (denoting the version) of the very
latest bundle release. Bundle versions are based upon the date of release, for
instance ``"20190904"``. If the latest version on GitHub is later than the
version ``circup`` currently has, then the latest version of the bundle
is automatically downloaded and cached away somewhere.

In this way, the ``circup`` tool is able to have available to it both a path
to a connected CIRCUITPYTHON devce and a copy of the latest version, including
the all important version information, of the Adafruit CircuitPython Bundle.

Exactly the same function (``get_modules``) is used to extract the metadata
from the modules on both the connected device and in the bundle cache. This
metadata is used to instantiate instances of the ``Module`` class which is
subsequently used to facilitate the various commands the tool makes available.

These commands are defined at the very end of the ``circup.py`` code.

Unit tests can be found in the ``tests`` directory. CircUp uses
`pytest <http://www.pytest.org/en/latest/>`_ style testing conventions. Test
functions should include a comment to describe its *intention*. We currently
have 100% unit test coverage for all the core functionality (excluding
functions used to define the CLI commands).

To run the full test suite, type::

    pytest --random-order --cov-config .coveragerc --cov-report term-missing --cov=circup

All code is formatted using the stylistic conventions enforced by
`black <https://black.readthedocs.io/en/stable/>`_. Python coding standard are
enforced by Pylint and verification of licensing is handled by REUSE. All of these
are run using pre-commit, which you can run by using::

    pip install pre-commit
    pre-commit run --all-files

Please see the output from ``pre-commit`` for more information about the various
available options to help you work with the code base.

Before submitting a PR, please remember to ``pre-commit run --all-files``.
But if  you forget the CI process in Github will run it for you. ;-)

CircUp uses the `Click <https://click.palletsprojects.com/en/7.x/>`_ module to
run command-line interaction. The
`AppDirs <https://pypi.org/project/appdirs/>`_ module is used to determine
where to store user-specific assets created by the tool in such a way that
meets the host operating system's usual conventions. The
`python-semver <https://github.com/k-bx/python-semver>`_ package is used to
validate and compare the semver values associated with modules. The ubiquitous
`requests <http://python-requests.org/>`_ module is used for HTTP activity.

Documentation, generated by `Sphinx <http://www.sphinx-doc.org/en/master/>`_,
is based on this README and assembled by assets in the ``doc`` subdirectory.
The latest version of the docs will be found on
`Read the Docs <https://circup.readthedocs.io/>`_.

Discussion of this tool happens on the Adafruit CircuitPython
`Discord channel <https://discord.gg/rqrKDjU>`_.