Onionprobe development¶
Onionprobe development guidelines and workflow are listed here.
Release procedure¶
Release cycle workflow.
Version update¶
Set the version number:
ONIONPROBE_VERSION=1.4.0
Update the version in some files, like:
dch -i # debian/changelog
$EDITOR packages/onionprobe/config.py
$EDITOR docker-compose.yml
$EDITOR setup.cfg
Regenerate the manpages¶
make manpages
Register the changes¶
Update the ChangeLog:
$EDITOR ChangeLog
Commit and tag:
git diff # review
git commit -a -m "Feat: Onionprobe $ONIONPROBE_VERSION"
git tag -s $ONIONPROBE_VERSION -m "Onionprobe $ONIONPROBE_VERSION"
Push changes and tags. Example:
git push origin && git push upstream
git push origin --tags && git push upstream --tags
Once a tag is pushed, a GitLab release is created.
Build packages¶
Build the Python package:
make build-python-package
Install this package in a fresh virtual machine. Example:
sudo apt-get install -y python3-pip tor
pip install --break-system-packages \
dist/onionprobe-$ONIONPROBE_VERSION-*.whl
Then test it:
$HOME/.local/bin/onionprobe --version
$HOME/.local/bin/onionprobe -e \
http://2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion
$HOME/.local/bin/onionprobe -e \
https://v236xhqtyullodhf26szyjepvkbv6iitrhjgrqj4avaoukebkk6n6syd.onion
If the package worked, upload it to the Test PyPI instance:
make upload-python-test-package
Install again the test package, by fetching it from Test PyPI, and in another fresh virtual machine:
sudo apt-get install -y python3-pip tor
pip install -i https://pypi.org/simple/ \
--extra-index-url https://test.pypi.org/simple \
--break-system-packages \
onionprobe==$ONIONPROBE_VERSION
Do the tests again in this new installation. If the the package works as expected, upload it to PyPI:
make upload-python-package
Finally, install the package one more time, but now fetching it from PyPI, and in yet another fresh virtual machine:
sudo apt-get install -y python3-pip tor
pip install --break-system-packages \
onionprobe==$ONIONPROBE_VERSION
Do the tests once more, in this new installation.
Announcement¶
Announce the new release:
- Post a message to the Tor Forum, using the onion-services-announce tag.
- Send a message to the tor-announce mailing list ONLY in special cases,
like important security issues (severity
HIGH
orCRITICAL
).
Template:
Subject: [RELEASE] Onionprobe [security] release $ONIONPROBE_VERSION
Greetings,
We just released [Onionprobe][] $ONIONPROBE_VERSION, a tool for testing and
monitoring the status of Onion Services.
[This release fixes a security issue. Please upgrade as soon as possible!]
[This release [also] requires a database migration for those using the monitoring node:]
[https://onionservices.torproject.org/apps/web/onionprobe/upgrading/]
[Onionprobe]: https://onionservices.torproject.org/apps/web/onionprobe
# ChangeLog
$CHANGELOG
Testing¶
Writing and trying alerts and unit tests for Prometheus¶
The Prometheus alerts shipped by Onionprobe are tested by the promtool
CI job.
The configuration is available under the configs/prometheus folder.
Workflow¶
A quick workflow to try tests before pushing to CI can be set with the standalone node:
./onionprobe-monitor up
./onionprobe-monitor shell prometheus
promtool test rules /etc/prometheus/prometheus-tests.yml
Once the new alerts and corresponding unit tests are updated, don't forget to also update the troubleshooting docs.
References¶
References for understanding and writing unit tests for Prometheus: