Contributing#

All command lines in code block are run from root folder khloraa_scaffolding/

How to use stable package#

Be sure the tests passed, see section Developing: package engineering resources, subsection Using tests with tox.

Configure environment#

  • Install the environment

    ./config/install_venv39.sh --dev

  • Source the environment

    source .venv_39-dev/bin/activate

Test it#

# khloraa_scaffolding/
(.venv_39-dev) ./tests/example/run_example.sh

c.f. tests/run_example.sh

Developing: package engineering resources#

All strictly necessary packages are listed in config/requirements.txt.

Tox introduction#

You don’t need to be in a python environment, just be in a bash one.

  • Some automatic running closed python environments are configured thought the tox environment manager.

  • No need to install packages, all is done thanks to tox.ini metadata.

  • To call a tox listed environment, use:

# khloraa_scaffolding/

tox -e the_env_name

Using tests with tox#

For re-use: All dependencies are stored in config/requirements-tests.txt.

# khloraa_scaffolding/

# Print in std output if pytest tests passed and the tests coverage.
tox -e report

Concrete used:

  • pytest watch files which matches test_* RegEx in watched directories (listed in tox.ini):

    # tox.ini
[pytest]
testpaths =
    tests

  • Open tests/htmlcov/index.html in a navigator to see which python lines are not covered by tests.

  • Add tests, re-run, and refresh the HTML webpage!

Pytest fixture:

In case you want to use an object that can out a file during its creation, you might want after test use removing the outputs. The idea is to use

  • DOCU continue with fixture

Look at pytest documentation https://docs.pytest.org/en/6.2.x/

Using linters with tox#

# khloraa_scaffolding/

# Print in std output the linters results:
tox -e linters

For re-use: All dependencies are stored in config/requirements-linters.txt.

Compute the docs with tox#

# khloraa_scaffolding/

# Compute documentation in:
# - docs/build/html:
tox -e docs-html

For re-use: All dependencies are stored in config/requirements-docs.txt.

Dealing with new package version#

Update the changelog#

Complete regularly the docs/src/changelog.md file:

  • [Unreleased] section until new release

  • [M.m.p] section when decide to release a new version (M: Major, m: minor, p: patch)

See Keep a Changelog link for more details.

Keyword

Definition

Added

for new features.

Changed

for changes in existing functionality.

Deprecated

for once-stable features removed in upcoming releases.

Removed

for deprecated features removed in this release.

Fixed

for any bug fixes.

Security

to invite users to upgrade in case of vulnerabilities.