docs: Update contributing documentation (#876)

* docs: Update contributing documentation

* Add change file

.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"

.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 }}

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
 ```

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