From c41e7991a76a83e56cceb3bd4981b970d6ba8af9 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Fri, 3 Nov 2023 19:28:28 -0700 Subject: [PATCH 1/4] poetry: Poetry 1.7 issues 1. Add --no-root to poetry invocations. Poetry 1.7 displays an error otherwise (though things still work) https://github.com/orgs/python-poetry/discussions/8622 https://github.com/python-poetry/poetry/issues/1132 2. Document https://github.com/python-poetry/poetry/issues/8623 --- .github/scripts/docs-build-deploy | 5 +++-- .github/workflows/build.yml | 2 +- .github/workflows/release.yml | 2 +- docs/contributing.md | 13 ++++++++----- 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/.github/scripts/docs-build-deploy b/.github/scripts/docs-build-deploy index 3b94fdc1bb..0c716e22c1 100755 --- a/.github/scripts/docs-build-deploy +++ b/.github/scripts/docs-build-deploy @@ -9,9 +9,10 @@ set -ev export "SITE_URL_FOR_MKDOCS=$1"; shift -# https://github.com/python-poetry/poetry/issues/1917 +# https://github.com/python-poetry/poetry/issues/1917 and +# https://github.com/python-poetry/poetry/issues/8623 export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring -poetry install # Only really needed once per environment unless there are updates +poetry install --no-root # Only really needed once per environment unless there are updates # TODO(ilyagr): The new default "alias-type" is symlink, we should consider # switching to it. poetry run -- mike deploy --alias-type redirect "$@" diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7df650783b..e2e0d65c89 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -75,7 +75,7 @@ jobs: with: poetry-version: latest - name: Install dependencies - run: poetry install + run: poetry install --no-root - name: Check that `mkdocs` can build the docs run: poetry run -- mkdocs build --strict diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 33a33aca29..a5fd4ceab9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -91,7 +91,7 @@ jobs: poetry-version: latest - name: Compile docs and zip them up run: | - poetry install + poetry install --no-root poetry run -- mkdocs build -f mkdocs-offline.yml archive="jj-${{ github.event.release.tag_name }}-docs-html.tar.gz" tar czf "$archive" -C "rendered-docs" . diff --git a/docs/contributing.md b/docs/contributing.md index b3c8cd91df..dc9fc2d9a4 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -184,13 +184,16 @@ Once you have `poetry` installed, you should ask it to install the rest of the required tools into a virtual environment as follows: ```shell -poetry install +# --no-root avoids a harmless error message starting with Poetry 1.7 +poetry install --no-root ``` -If you get requests to "unlock a keyring" or error messages about failing to do -so, this is a [known `poetry` -bug](https://github.com/python-poetry/poetry/issues/1917). The workaround is to -run the following and then to try `poetry install` again: +You may get requests to "unlock a keyring", [an error messages about failing to +do so](https://github.com/python-poetry/poetry/issues/1917), or, in the case of +Poetry 1.7, it may [simply hang +indefinitely](https://github.com/python-poetry/poetry/issues/8623). The +workaround is to either to unlock the keyring or to run the following, and then +to try `poetry install --no-root` again: ```shell # For sh-compatible shells or recent versions of `fish` From 21db5aec36d44bfa4cdd0c427129a03c4864af74 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sun, 5 Nov 2023 15:24:38 -0800 Subject: [PATCH 2/4] poetry: create a CI with Debian stable's version of `poetry`. This is mainly for our own information. It doesn't have to be a required check. --- .github/workflows/build.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index e2e0d65c89..b17682ca3d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -79,6 +79,26 @@ jobs: - name: Check that `mkdocs` can build the docs run: poetry run -- mkdocs build --strict + mkdocs-old-poetry: + name: Check that MkDocs can build the docs with Poetry 1.3.2 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 + - uses: actions/setup-python@v4 + with: + python-version: 3.11 + - name: Install poetry + uses: abatilo/actions-poetry@v2 + with: + # Test with the version of Poetry in Debian stable. If this starts + # failing, we should increase this version and document the minimum + # necessary version of Poetry in contributing.md. + poetry-version: 1.3.2 + - name: Install dependencies + run: poetry install --no-root + - name: Check that `mkdocs` can build the docs + run: poetry run -- mkdocs build --strict + cargo-deny: runs-on: ubuntu-latest strategy: From 6e4044e6c17226081abd1e3ac564a6c5a4543afc Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Thu, 2 Nov 2023 22:47:47 -0700 Subject: [PATCH 3/4] poetry: Update pyproject.toml to use newer convention The previous commit checks that Poetry down to version 1.3.2 (current Debian stable version) support it. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 0a8fd998c9..1cf5fca212 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,7 @@ authors = [] [tool.poetry.dependencies] python = "^3.8" -[tool.poetry.dev-dependencies] +[tool.poetry.group.dev.dependencies] # These can be updated with `poetry add`. mkdocs = "^1.5.2" mkdocs-material = "^9.4" From ef501b8f4d933804a88298c227a51068453cd8e5 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sun, 5 Nov 2023 15:23:06 -0800 Subject: [PATCH 4/4] website: Stop `mike` from always changing `sitemaps.xml.gz` Originally, my motivation was to try again to get `mike` to not push empty commits (which this should do). I'm now reconsidering this, since *not* pushing empty commits will make the output of the CI job a little harder to read. If this becomes an issue, I might even add `--allow-empty` to the `mike` invocations later. A more important motivation is that even for a 400-byte file, changing it for every PR blows up the size of the repo eventually. The cause for the changes to this file was that `gzip` stores a timestamp inside the `.gz` file. --- .github/scripts/docs-build-deploy | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/scripts/docs-build-deploy b/.github/scripts/docs-build-deploy index 0c716e22c1..12a426b35d 100755 --- a/.github/scripts/docs-build-deploy +++ b/.github/scripts/docs-build-deploy @@ -9,6 +9,10 @@ set -ev export "SITE_URL_FOR_MKDOCS=$1"; shift +# Affects the generation of `sitemap.xml.gz` by `mkdocs`. See +# https://github.com/jimporter/mike/issues/103 and +# https://reproducible-builds.org/docs/source-date-epoch/ +export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct docs/ mkdocs.yml) # https://github.com/python-poetry/poetry/issues/1917 and # https://github.com/python-poetry/poetry/issues/8623 export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring