From 448ade1195a336f282af596e54e6c7fa7b9f77c4 Mon Sep 17 00:00:00 2001 From: "Edgar R. M" Date: Sat, 3 Jun 2023 12:16:16 -0600 Subject: [PATCH] docs: Update contributing documentation (#876) * docs: Update contributing documentation * Add change file --- .../Documentation-20230603-121438.yaml | 5 ++ .github/workflows/gen-release-pr.yml | 2 +- docs/contributing/docker.md | 49 +++++++++++-------- docs/contributing/release.md | 20 +++++--- 4 files changed, 47 insertions(+), 29 deletions(-) create mode 100644 .changes/unreleased/Documentation-20230603-121438.yaml diff --git a/.changes/unreleased/Documentation-20230603-121438.yaml b/.changes/unreleased/Documentation-20230603-121438.yaml new file mode 100644 index 00000000..38d30da0 --- /dev/null +++ b/.changes/unreleased/Documentation-20230603-121438.yaml @@ -0,0 +1,5 @@ +kind: Documentation +body: Update contributing documentation +time: 2023-06-03T12:14:38.43441-06:00 +custom: + Issue: "876" diff --git a/.github/workflows/gen-release-pr.yml b/.github/workflows/gen-release-pr.yml index b47bf76a..291ce34a 100644 --- a/.github/workflows/gen-release-pr.yml +++ b/.github/workflows/gen-release-pr.yml @@ -32,7 +32,7 @@ jobs: args: "\ batch ${{ github.event.inputs.next-version }} - ${{ github.event.inputs.prerelease && format('-p {0}', github.event.inputs.prerelease) || '--remove-prereleases' }} + ${{ github.event.inputs.prerelease && format('-p {0}', github.event.inputs.prerelease) }} ${{ github.event.inputs.metadata && format('-m {0}', github.event.inputs.metadata) }}" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/contributing/docker.md b/docs/contributing/docker.md index aabfee71..a91df1bb 100644 --- a/docs/contributing/docker.md +++ b/docs/contributing/docker.md @@ -11,60 +11,67 @@ Now you can access LimeSurvey at [port 8001](http://localhost:8001/index.php/adm ## Other LimeSurvey versions -By default, citric is tested against the latest `5-apache` tag of LimeSurvey. +By default, citric is tested against the latest `6-apache` tag of LimeSurvey. If you want to use [a different tag](https://hub.docker.com/r/martialblog/limesurvey/tags), you can specify it using the `LS_IMAGE_TAG` environment variable. ```shell -export LS_IMAGE_TAG=5.3.10-220419-apache +export LS_IMAGE_TAG=6.0.7+230515-apache docker compose up -d ``` ## Integration tests -Integrations tests rely on LimeSurver's PostgreSQL database being exposed to the -host, so you'll need to override the `db` service with the definition in -`docker-compose.test.yml`: +Docker Compose allows you to run integration tests against a local instance of +LimeSurvey. First you'll need to setup the environment variables: ```shell -docker-compose -d +export BACKEND=postgres +export LS_URL=http://localhost:8001/index.php/admin/remotecontrol +export LS_USER=iamadmin +export LS_PASSWORD=secret +export LS_VERSION=6-apache ``` -Now you can run the tests mark as `integration_test`: +Then you can run the tests with Nox: ```shell -nox -rs tests --python "3.10" -- -m "integration_test" +nox -rs integration +``` + +```{tip} +You can use the `--force-python` option to run the tests on a different +Python version from the default one (`3.11`). ``` ### Run integraton tests on a specific LimeSurvey version ```shell -export LS_IMAGE_TAG='5.3.10-220419-apache' +export LS_IMAGE_TAG='6.0.7+230515-apache' docker-compose -d -nox -rs tests --python "3.10" -- -m "integration_test" +nox -rs integration ``` -### Run integraton tests on unreleased LimeSurvey version +### Run integraton tests against an unreleased LimeSurvey version ```shell export DOCKER_BUILDKIT=0 -export LS_VERSION=5af7b00a674ecb872cd2f359366946f572af69b0 -export LS_CHECKSUM=f21777810430c533929f51f5999e2b3bed0fc9c9921a461f21376b83a45fad9b +export LS_VERSION=f148781ec57fd1a02e5faa26a7465d78c9ab5dfe +export LS_CHECKSUM=64aec410738b55c51045ac15373e2bc376e67cd6e20938d759c4596837ef6154 -docker-compose \ +docker compose \ -f docker-compose.yml \ -f docker-compose.ref.yml up \ -d -nox -rs tests --python "3.10" -- -m "integration_test" +nox -rs integration ``` -Where `LS_VERSION` is the commit SHA at the point of interest, while `LS_CHECKSUM` +Where `LS_VERSION` is the commit SHA at the point of interest and `LS_CHECKSUM` is the SHA256 checksum of the `.tar.gz` archive of the project at that commit. - ````{tip} You can obtain the checksum by running: @@ -77,10 +84,10 @@ sha256sum ${LS_VERSION}.tar.gz To test against such a version in CI, add the following to the job matrix: ```yaml -- python-version: "3.10" +- python-version: "3.11" os: "ubuntu-latest" session: "integration" - experimental: false - limesurvey_version: 5af7b00a674ecb872cd2f359366946f572af69b0 - limesurvey_checksum: f21777810430c533929f51f5999e2b3bed0fc9c9921a461f21376b83a45fad9b + limesurvey_version: "f148781ec57fd1a02e5faa26a7465d78c9ab5dfe" + database: postgres + experimental: true ``` diff --git a/docs/contributing/release.md b/docs/contributing/release.md index 6eedb509..3980e503 100644 --- a/docs/contributing/release.md +++ b/docs/contributing/release.md @@ -1,18 +1,24 @@ # Publish a new version to PyPI -1. Trigger the [Generate release Pull Request][gen-release-pr] workflow with the -desired package version. +1. Trigger the [Generate release Pull Request][gen-release-pr] workflow. The [GitHub CLI](https://github.com/cli/cli/) is very convenient for this: ```console - $ gh workflow run - ? Select a workflow Generate release Pull Request (gen-release-pr.yml) - ? changie-version 1.7.0 - ? next-version patch + $ gh workflow run gen-release-pr.yml ✓ Created workflow_dispatch event for gen-release-pr.yml at main + + To see runs for this workflow, try: gh run list --workflow=gen-release-pr.yml + ``` + + ````{tip} + You can specify the bump type, prerelease and metadata with the `-f` option: + + ```shell + gh workflow run gen-release-pr.yml -f next-version=minor -f prerelease=b1 ``` + ```` -1. Create a [release](https://github.com/edgarrmondragon/citric/releases/new). +1. Validate the release notes and publish the generated [draft release](https://github.com/edgarrmondragon/citric/releases). [gen-release-pr]: https://github.com/edgarrmondragon/citric/actions/workflows/gen-release-pr.yml