Skip to content

Commit

Permalink
deploy: 612dd23
Browse files Browse the repository at this point in the history
  • Loading branch information
@johannesjh
johannesjh committed Jul 7, 2024
1 parent ced40af commit 6905771
Show file tree
Hide file tree
Showing 6 changed files with 56 additions and 103 deletions.
Binary file modified docs/.doctrees/cli.doctree
View file
Binary file not shown.
Binary file modified docs/.doctrees/development.doctree
View file
Binary file not shown.
Binary file modified docs/.doctrees/environment.pickle
View file
Binary file not shown.
77 changes: 25 additions & 52 deletions docs/_sources/development.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,68 +137,41 @@ We welcome your contributions even if your workflow differs from what we recomme
Updating Dependencies
---------------------

There are three categories of dependencies that can be found in this repository:
*Github Actions*, *Poetry* and *pre-commit hooks*.
Currently there is no programmatic way to update the github actions we depend on.
One has to manually update the commit hashes used.

Poetry dependencies
```````````````````

Poetry differentiates between direct and indirect dependencies.
Direct dependencies are specified in ``pyproject.toml`` -- usually with a fixed version.
Updating these can introduce bugs through breaking changes in the API exposed by
these dependencies. That's why we'll focus on updating indirect dependencies first.
Running the following and committing the resulting changes to ``poetry.lock`` will
do the trick provided that set up *pre-commit* according to this guide.


.. code:: bash
# 1. Update indirect dependencies (stored in poetry.lock)
poetry update
# 2. Stage and commit (runs pre-commit hooks)
There are multiple categories of dependencies that can be found in this repository:
CI, Poetry and pre-commit hooks.

Direct dependencies are updated by changing the version specified in ``pyproject.toml``.
You will have to manually identify the latest version for a package by opening
its project page on `pypi <https://pypi.org/project/{name}/>`_.


.. code:: bash
# 1. Determine latest version of a package.
# 2. Update version requirement in `pyproject.toml`
# 3. Update `poetry.lock` (`--no-update` will prevent updating indirect dependencies)
poetry lock --no-update
# 4. Install newest version (adjust options to your dev env)
poetry install --with lint --all-extras
# 5. Stage and commit (runs pre-commit hooks)
CI dependencies
```````````````

Github actions and workflows contain hardcoded versions of container images and packages.
See the ``.github`` folder.
Currently there is no programmatic way to update the github actions we depend on.
One has to manually update the versions and/or commit hashes.

Pre-commit hooks
````````````````
The devcontainer configuration file also contains versions,
these are also manually kept up-to-date.
See the ``.devcontainer`` folder.

Pre-commit hooks require a bit more steps to update because they are partially
synced with the versions specified in ``poetry.lock``.

Poetry and pre-commit dependencies
``````````````````````````````````

.. code:: bash
First update poetry dependencies,

# 1. Update pre-commit hooks
pre-commit autoupdate --freeze
#. Manually bump the version constraints in the ``pyproject.toml`` file.
#. Run ``poetry update --with lint`` to update installed packages and write the lock file.
#. Stage changes by running ``git add pyproject.toml poetry.lock``.

# 2. Stage `.pre-commit-config.yaml`
git add .pre-commit-config.yaml

# 3. Sync with poetry
pre-commit run
Then update pre-commit dependencies,

# 4. Remove `frozen: x.x.x` comments for unfrozen dependencies
# 5. Stage and commit (runs pre-commit hooks)
#. Run ``pre-commit install`` just to be sure that pre-commit is properly initialized.
#. Run ``pre-commit autoupdate --freeze`` to update pre-commit's packages.
#. Stage changes by running ``git add .pre-commit-config.yaml``.
#. Run ``pre-commit run`` to sync package versions from poetry to pre-commit. Note that this is a one-way-sync, i.e., `sync_with_poetry <https://github.com/floatingpurr/sync_with_poetry>`_ will copy package versions from the poetry lock file into the pre-commit yaml file.
#. Stage changes by running ``git add .pre-commit-config.yaml``.
#. run ``pre-commit run`` to verify that pre-commit now happily leaves all files unchanged.
#. Stage and commit all changes.


Publishing a Release
Expand Down
80 changes: 30 additions & 50 deletions docs/development.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@
<li class="toctree-l2"><a class="reference internal" href="#running-tests">Running Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#ensuring-code-quality">Ensuring Code quality</a></li>
<li class="toctree-l2"><a class="reference internal" href="#updating-dependencies">Updating Dependencies</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#poetry-dependencies">Poetry dependencies</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pre-commit-hooks">Pre-commit hooks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#ci-dependencies">CI dependencies</a></li>
<li class="toctree-l3"><a class="reference internal" href="#poetry-and-pre-commit-dependencies">Poetry and pre-commit dependencies</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#publishing-a-release">Publishing a Release</a></li>
Expand Down Expand Up @@ -214,56 +214,36 @@ <h2>Ensuring Code quality<a class="headerlink" href="#ensuring-code-quality" tit
</section>
<section id="updating-dependencies">
<h2>Updating Dependencies<a class="headerlink" href="#updating-dependencies" title="Permalink to this heading"></a></h2>
<p>There are three categories of dependencies that can be found in this repository:
<em>Github Actions</em>, <em>Poetry</em> and <em>pre-commit hooks</em>.
<p>There are multiple categories of dependencies that can be found in this repository:
CI, Poetry and pre-commit hooks.</p>
<section id="ci-dependencies">
<h3>CI dependencies<a class="headerlink" href="#ci-dependencies" title="Permalink to this heading"></a></h3>
<p>Github actions and workflows contain hardcoded versions of container images and packages.
See the <code class="docutils literal notranslate"><span class="pre">.github</span></code> folder.
Currently there is no programmatic way to update the github actions we depend on.
One has to manually update the commit hashes used.</p>
<section id="poetry-dependencies">
<h3>Poetry dependencies<a class="headerlink" href="#poetry-dependencies" title="Permalink to this heading"></a></h3>
<p>Poetry differentiates between direct and indirect dependencies.
Direct dependencies are specified in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> – usually with a fixed version.
Updating these can introduce bugs through breaking changes in the API exposed by
these dependencies. That’s why we’ll focus on updating indirect dependencies first.
Running the following and committing the resulting changes to <code class="docutils literal notranslate"><span class="pre">poetry.lock</span></code> will
do the trick provided that set up <em>pre-commit</em> according to this guide.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># 1. Update indirect dependencies (stored in poetry.lock)</span>
poetry<span class="w"> </span>update

<span class="c1"># 2. Stage and commit (runs pre-commit hooks)</span>
</pre></div>
</div>
<p>Direct dependencies are updated by changing the version specified in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>.
You will have to manually identify the latest version for a package by opening
its project page on <a class="reference external" href="https://pypi.org/project/{name}/">pypi</a>.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># 1. Determine latest version of a package.</span>
<span class="c1"># 2. Update version requirement in `pyproject.toml`</span>
<span class="c1"># 3. Update `poetry.lock` (`--no-update` will prevent updating indirect dependencies)</span>
poetry<span class="w"> </span>lock<span class="w"> </span>--no-update

<span class="c1"># 4. Install newest version (adjust options to your dev env)</span>
poetry<span class="w"> </span>install<span class="w"> </span>--with<span class="w"> </span>lint<span class="w"> </span>--all-extras

<span class="c1"># 5. Stage and commit (runs pre-commit hooks)</span>
</pre></div>
</div>
One has to manually update the versions and/or commit hashes.</p>
<p>The devcontainer configuration file also contains versions,
these are also manually kept up-to-date.
See the <code class="docutils literal notranslate"><span class="pre">.devcontainer</span></code> folder.</p>
</section>
<section id="pre-commit-hooks">
<h3>Pre-commit hooks<a class="headerlink" href="#pre-commit-hooks" title="Permalink to this heading"></a></h3>
<p>Pre-commit hooks require a bit more steps to update because they are partially
synced with the versions specified in <code class="docutils literal notranslate"><span class="pre">poetry.lock</span></code>.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># 1. Update pre-commit hooks</span>
pre-commit<span class="w"> </span>autoupdate<span class="w"> </span>--freeze

<span class="c1"># 2. Stage `.pre-commit-config.yaml`</span>
git<span class="w"> </span>add<span class="w"> </span>.pre-commit-config.yaml

<span class="c1"># 3. Sync with poetry</span>
pre-commit<span class="w"> </span>run

<span class="c1"># 4. Remove `frozen: x.x.x` comments for unfrozen dependencies</span>
<span class="c1"># 5. Stage and commit (runs pre-commit hooks)</span>
</pre></div>
</div>
<section id="poetry-and-pre-commit-dependencies">
<h3>Poetry and pre-commit dependencies<a class="headerlink" href="#poetry-and-pre-commit-dependencies" title="Permalink to this heading"></a></h3>
<p>First update poetry dependencies,</p>
<ol class="arabic simple">
<li><p>Manually bump the version constraints in the <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">poetry</span> <span class="pre">update</span> <span class="pre">--with</span> <span class="pre">lint</span></code> to update installed packages and write the lock file.</p></li>
<li><p>Stage changes by running <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">pyproject.toml</span> <span class="pre">poetry.lock</span></code>.</p></li>
</ol>
<p>Then update pre-commit dependencies,</p>
<ol class="arabic simple">
<li><p>Run <code class="docutils literal notranslate"><span class="pre">pre-commit</span> <span class="pre">install</span></code> just to be sure that pre-commit is properly initialized.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">pre-commit</span> <span class="pre">autoupdate</span> <span class="pre">--freeze</span></code> to update pre-commit’s packages.</p></li>
<li><p>Stage changes by running <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">.pre-commit-config.yaml</span></code>.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">pre-commit</span> <span class="pre">run</span></code> to sync package versions from poetry to pre-commit. Note that this is a one-way-sync, i.e., <a class="reference external" href="https://github.com/floatingpurr/sync_with_poetry">sync_with_poetry</a> will copy package versions from the poetry lock file into the pre-commit yaml file.</p></li>
<li><p>Stage changes by running <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">.pre-commit-config.yaml</span></code>.</p></li>
<li><p>run <code class="docutils literal notranslate"><span class="pre">pre-commit</span> <span class="pre">run</span></code> to verify that pre-commit now happily leaves all files unchanged.</p></li>
<li><p>Stage and commit all changes.</p></li>
</ol>
</section>
</section>
<section id="publishing-a-release">
Expand Down
2 changes: 1 addition & 1 deletion docs/searchindex.js
View file

Large diffs are not rendered by default.

0 comments on commit 6905771

Please sign in to comment.