Contributing¶
I’m not a coder!¶
Submit an issue explaining the issue thoroughly. Not everyone can code and there is no shame in that.
End of the day, world+dog wants featureful well written packages which stay on mission and within the resources and talent at the teams disposal.
Issues and PRs¶
Create an issue first. Get feedback. And if the feedback is favorable, do the work and submit a PR, in a branch, with a mention to the issue.
The trick is to keep the commit scope as small as possible. Ideally should do only one thing.
PR should come with:
unittests
Sphinx in-code documentation. Not dependent upon Overview
If an issue or PR is not dealt with in a timely manner, optionally can send a reminder to maintainer on mastodon
New features¶
The rules might get tossed aside. Take risk; be bold.
Expect feedback asking for changes. Be patient, make whatever changes are requested.
Setup venvs¶
Will be setting up two venv
code base |
Python version |
|---|---|
docs |
py310 |
package |
py39 |
Assumes using pyenv
docs venv¶
pyenv
mkdir .doc
cd .doc
pyenv versions
Assuming py310 version is 3.10.14
touch .python-version
echo "3.10.14" > .python-version
Check active version
pyenv version
3.10.14
setup docs venv and install dependencies
mkdir -p .doc/.venv
cd .doc
echo "3.10.14" >> .python-version
python -m venv .venv
. .venv/bin/activate
python -m pip install -r ../docs/pip-tools.lock -r ../docs/requirements.lock
cd ../docs
make htmlall
make linkcheck
When using pip install -r NEVER break command into multiple calls.
Update docs requirements¶
activate doc venv then run
cd docs
make doc_upgrade
package venv¶
.python-version goes into the package base folder parent, not the package base folder
pyenv version
3.10.14
mkdir .venv
cd .venv
echo "3.10.14" >> .python-version
python -m venv .
. .venv/bin/activate
python -m pip install -r ../requirements/pip-tools.lock -r ../requirements/prod.unlock -r ../requirements/kit.lock -r ../requirements/manage.lock -r ../requirements/dev.lock
When using pip install -r NEVER break command into multiple calls.
Everything except docs
Update package requirements¶
activate package venv then run
. .venv/bin/activate
reqs fix --venv-relpath='.venv'
cd .tox && tox -r --root=.. -c ../tox-req.ini -e docs --workdir=.; cd - &>/dev/null
The 1st command runs within the current active venv. The packages default. So the python interpreter version is already known.
The 2nd command lets tox choose the python interpreter version and create the venv, and run the command. These python interpreter versions are not the same!
The lock process will upgrade the dependency versions and enforce any package version restrictions; specifiers and qualifiers are recognized and applied.
Setup – tox¶
pyenv installed versions
pyenv versions
The .tox/.python-version needs all the versions tox will have access to
mkdir .tox
cd .tox
touch .python-version
cat <<-EOF > .python-version
3.10.14
3.11.9
3.12.4
3.13.3
pypy3.10-7.3.16
EOF
Assuming package venv is already activated
python -m pip install -r requirements/tox.lock
Then use tox
tox -r -e lint
tox -r -e mypy
tox -r -e pre-commit
tox -r -e interrogate
cd .tox && tox -r --root=.. -c ../tox-test.ini -e pypy3 --workdir=.; cd - &>/dev/null
tox -r -e docs
-r long form is --recreate. tox only needed to recreate venv when
dependencies change. Or whenever feel the itch.
For running coverage, python version can be changed, e.g. -e pypy3.
