From fbe05065c970dc849515629e89cc91e20b1f670d Mon Sep 17 00:00:00 2001 From: Alex Pyrgiotis Date: Wed, 4 Dec 2024 14:06:32 +0200 Subject: [PATCH] docs: Update release instructions Update our release instructions with a way to run manual tasks via `doit`. Also, add developer documentation on how to use `doit`, and some tips and tricks. --- RELEASE.md | 23 +++++++++++---- docs/developer/doit.md | 67 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+), 5 deletions(-) create mode 100644 docs/developer/doit.md diff --git a/RELEASE.md b/RELEASE.md index 39f9564ff..38f7e5af8 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -76,7 +76,16 @@ Once we are confident that the release will be out shortly, and doesn't need any ### macOS Release -This needs to happen for both Silicon and Intel chipsets. +> [!TIP] +> You can automate these steps from your macOS terminal app with: +> +> ``` +> export APPLE_ID= +> make build-macos-intel # for Intel macOS +> make build-macos-arm # for Apple Silicon macOS +> ``` + +The following needs to happen for both Silicon and Intel chipsets. #### Initial Setup @@ -217,12 +226,16 @@ Rename `Dangerzone.msi` to `Dangerzone-$VERSION.msi`. ### Linux release -> [!INFO] -> Below we explain how we build packages for each Linux distribution we support. +> [!TIP] +> You can automate these steps from any Linux distribution with: +> +> ``` +> make build-linux +> ``` > -> There is also a `release.sh` script available which creates all -> the `.rpm` and `.deb` files with a single command. +> You can then add the created artifacts to the appropriate APT/YUM repo. +Below we explain how we build packages for each Linux distribution we support. #### Debian/Ubuntu diff --git a/docs/developer/doit.md b/docs/developer/doit.md new file mode 100644 index 000000000..a461d967a --- /dev/null +++ b/docs/developer/doit.md @@ -0,0 +1,67 @@ +# Using the Doit Automation Tool + +Developers can use the [Doit](https://pydoit.org/) automation tool to create +release artifacts. The purpose of the tool is to automate the manual release +instructions in `RELEASE.md` file. Not everything is automated yet, since we're +still experimenting with this tool. You can find our task definitions in this +repo's `dodo.py` file. + +## Why Doit? + +We picked Doit out of the various tools out there for the following reasons: + +* **Pythonic:** The configuration file and tasks can be written in Python. Where + applicable, it's easy to issue shell commands as well. +* **File targets:** Doit borrows the file target concept from Makefiles. Tasks + can have file dependencies, and targets they build. This makes it easy to + define a dependency graph for tasks. +* **Hash-based caching:** Unlike Makefiles, doit does not look at the + modification timestamp of source/target files, to figure out if it needs to + run them. Instead, it hashes those files, and will run a task only if the + hash of a file dependency has changed. +* **Parallelization:** Tasks can be run in parallel with the `-n` argument, + which is similar to `make`'s `-j` argument. + +## How to Doit? + +First, enter your Poetry shell. Then, make sure that your environment is clean, +and you have ample disk space. You can run: + +```bash +doit clean --dry-run # if you want to see what would happen +doit clean # you'll be asked to cofirm that you want to clean everything +``` + +Finally, you can build all the release artifacts with `doit`, or a specific task +with: + +``` +doit +``` + +## Tips and tricks + +* You can run `doit list --all -s` to see the full list of tasks, their + dependencies, and whether they are up to date. +* You can run `doit info ` to see which dependencies are missing. +* You can change this line in `pyproject.toml` to `true`, to allow using the + Docker/Podman build cache: + + ``` + use_cache = true + ``` + + > [!WARNING] + > Using caching may speed up image builds, but is not suitable for release + > artifacts. The ID of our base container image (Alpine Linux) does not change + > that often, but its APK package index does. So, if we use caching, we risk + > skipping the `apk upgrade` layer and end up with packages that are days + > behind. + +* You can pass the following environment variables to the script, in order to + affect some global parameters: + - `CONTAINER_RUNTIME`: The container runtime to use. Either `podman` (default) + or `docker`. + - `RELEASE_DIR`: Where to store the release artifacts. Default path is + `~/release-assets/` + - `APPLE_ID`: The Apple ID to use when signing/notarizing the macOS DMG.