Skip to content

development.rst

Latest commit

 

History

History
152 lines (102 loc) · 4.55 KB

development.rst

File metadata and controls

152 lines (102 loc) · 4.55 KB

Developing Zino

Development tools

A bunch of tools needed or recommended to have available when developing Zino and/or running its test suite are included in dependency groups in the pyproject.toml file (local:, online:).

The groups are:

  • test just for testing tools
  • maintenance for packagong and release tools
  • dev includes test and maintenance tools as weel as linters, formatters and other helpers.

Install all of them to your development virtualenv using pip (or uv pip):

pip install --group dev

Running tests

tox and pytest are used to run the test suite. To run the test suite on all supported versions of Python, run:

tox run

In order to run all the tests you need the non-python program snmptrap. On debian-derived distros it is included in the snmp package, install it via:

apt install snmp

If this package is not installed some tests will be skipped.

Code style

Zino code should follow the PEP-8 and PEP-257 guidelines. Ruff is used for automatic code formatting and linting. The pre-commit tool is used to enforce code styles at commit-time.

Before you start hacking, enable pre-commit hooks in your cloned repository, like so:

pre-commit install

Test trap examples

Running Zino during development might look like this (listening for traps on the non-privileged port 1162):

zino --trap-port 1162

To send an example trap (BGP4-MIB::bgpBackwardTransition, which Zino ignores by default), you can use a command like:

snmptrap -v2c -c public \
    127.0.0.1:1162 \
    '' \
    BGP4-MIB::bgpBackwardTransition \
    BGP4-MIB::bgpPeerRemoteAddr a 192.168.42.42 \
    BGP4-MIB::bgpPeerLastError x 4242 \
    BGP4-MIB::bgpPeerState i 2

Using towncrier to automatically produce the changelog

Before merging a pull request

To be able to automatically produce the changelog for a release one file for each pull request (also called news fragment) needs to be added to the folder changelog.d/.

The name of the file consists of three parts separated by a period: 1. The identifier: the issue number or the pull request number. If we don’t want to add a link to the resulting changelog entry then a + followed by a unique short description. 2. The type of the change: we use security, removed, deprecated, added, changed and fixed. 3. The file suffix, e.g. .md, towncrier does not care which suffix a fragment has.

So an example for a file name related to an issue/pull request would be 214.added.md or for a file without corresponding issue +fixed-pagination-bug.fixed.md.

This file can either be created manually with a file name as specified above and the changelog text as content or one can use towncrier to create such a file as following:

$ towncrier create -c "Changelog content" 214.added.md

When opening a pull request there will be a check to make sure that a news fragment is added and it will fail if it is missing.

Before a release

To add all content from the changelog.d/ folder to the changelog file simply run

$ towncrier build --version {version}

This will also delete all files in changelog.d/.

To preview what the addition to the changelog file would look like add the flag --draft. This will not delete any files or change CHANGELOG.md. It will only output the preview in the terminal.

A few other helpful flags: - date DATE - set the date of the release, default is today - keep - do not delete the files in changelog.d/

More information about towncrier.

Making git blame ignore formatting changes

The Zino codebase has been slightly reformatted a couple of times. To make git blame ignore these changes you can run

$ git config blame.ignoreRevsFile .git-blame-ignore-revs

For more information check the git blame docs.