upstream/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-06-04 22:33:00 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

update contributing

Browse source
This commit is contained in:
Brad Warren 2021-06-25 16:15:47 -04:00
parent 2b61a1025a
commit fdc19c037a
1 changed files with 45 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
certbot/docs/contributing.rst
View file

@ -566,6 +566,51 @@ and run the command:
This would generate the HTML documentation in ``_build/html`` in your current
``docs/`` directory.
Certbot's dependencies
======================
We attempt to pin all of Certbot's dependencies whenever we can for reliability
and consistency. Some of the places we have Certbot's dependencies pinned
include our snaps, Docker images, Windows installer, CI, and our development
environments.
In most cases, the file where dependency versions are specified is
``tools/requirements.txt``. There are two exceptions to this. The first is our
"oldest" tests where ``tools/oldest_constraints.txt`` is used instead. The
purpose of the "oldest" tests is to ensure Certbot continues to work with the
oldest versions of our dependencies which we claim to support. The second
exception to using ``tools/requirements.txt`` is in our unpinned tests. As of
writing this, there is one test we run nightly in CI where we leave Certbot's
dependencies unpinned. The thinking behind this test is to help us learn about
breaking changes in our dependencies so that we can respond accordingly.
The choices of whether Certbot's dependencies are pinned and what file is used
if they are should be automatically handled for you most of the time by
Certbot's tooling. The way it works though is ``tools/pip_install.py`` (which
many of our other tools build on) checks for the presence of environment
variables. If ``CERTBOT_NO_PIN`` is set to 1, Certbot's dependencies will not
be pinned. If that variable is not set and ``CERTBOT_OLDEST`` is set to 1,
``tools/oldest_constraints.txt`` will be used as constraints for ``pip``.
Otherwise, ``tools/requirements.txt`` is used as constraints.
Updating dependency versions
----------------------------
``tools/requirements.txt`` and ``tools/oldest_constraints.txt`` can be updated
using ``tools/pinning/normal/repin.sh`` and ``tools/pinning/oldest/repin.sh``
respectively. This works by using ``poetry`` to generate pinnings based on a
dummy Poetry project defined by the ``pyproject.toml`` file in the same
directory as the script. In many cases, you can just run the script to generate
updated dependencies, however, if you need to pin back packages or unpin
packages that were previously restricted to an older version, you will need to
modify the ``pyproject.toml`` file. The syntax used by this file is described
at https://python-poetry.org/docs/pyproject/ and how dependencies are specified
in this file is further described at
https://python-poetry.org/docs/dependency-specification/.
If you want to learn more about the design used here, see
``tools/pinning/DESIGN.md`` in the Certbot repo.
.. _docker-dev:
Running the client with Docker