doc: update README, address #40

.github/workflows/build-containers.yml

@@ -2,9 +2,13 @@ name: build-containers
 
 on:
   push:
+    paths-ignore:
+      - '**.adoc'
     tags:
       - "v*"
   pull_request:
+    paths-ignore:
+      - '**.adoc'
   workflow_dispatch:
   workflow_run:
     workflows: ["add-tag"]

README.adoc

@@ -1,72 +1,71 @@
-= Tebako Docker containers
+= Tebako Docker Containers
 
-== Pre-built containers
-
-This repository contains definitions of Docker containers with a preinstalled
-Tebako packaging environment, and provides those built Docker containers.
-
-Tebako containers offer a streamlined and isolated environment for packaging
-applications, ensuring consistency and reproducibility across different
-development setups. By using containers, developers can bypass the complexities
-of managing multiple dependencies on their local machines.
+== What is Tebako?
 
+Tebako is an executable packager designed to simplify the process of packaging applications that rely on an interpretive runtime, making distribution easier. It packages a set of files into a DwarFS file system for read-only purposes.
 
+For more details, visit the https://www.tebako.org[Tebako website].
 
-== What is Tebako?
+== Pre-built Containers
 
-Tebako is an executable packager that simplifies the process of packaging applications
-that utilize an interpretive runtime, allowing for easy distribution.
+Tebako packages for Linux systems must be created on the same architecture and standard library implementation as the target system. For example:
 
-It packages a set of files into a DwarFS file system for read-only purposes.
+- **x86_64/aarch64 packages** require **x86_64/aarch64 systems**, respectively.
+- Packages compatible with **GNU/musl Linux** must be created in **GNU/musl environments**.
 
-Please refer to the https://www.tebako.org[Tebako website] for more details.
+Installing Tebako on different Linux configurations can be cumbersome, and our testing is limited to a specific set of Ubuntu and Alpine configurations.
 
+== Available Container Tags
 
+Tebako containers are available to support packaging for both GNU and musl target environments. The currently available tags are:
 
-== Available container tags
+=== `ubuntu-20.04`
 
-Tebako containers are available with different base images to suit various needs.
+This container is based on **Ubuntu 20.04 LTS**, providing an environment for packaging applications for GNU systems that use the https://sourceware.org/glibc[`glibc` implementation of the C standard library].
 
-The currently available tags are:
+The `--patchelf` option enables the creation of packages that are forward-compatible with GNU Linux distributions running GLIBC version 2.31 and above.
 
-`ubuntu-20.04`::
-This container is based on Ubuntu 20.04 LTS (`glibc`), providing a stable and
-widely used environment for packaging.
+.Minimum versions of GLIBC Linux distributions that support Tebako packages with forward portability
+[cols="3", options="header"]
+|===
+| Distribution | Minimal Supported Version | GLIBC Version
+| Ubuntu | 20.04 (Focal Fossa) | GLIBC 2.31
+| Debian | 11 (Bullseye) | GLIBC 2.31
+| Rocky Linux | 9 | GLIBC 2.34
+| Fedora | 33 | GLIBC 2.32
+| CentOS | 9 | GLIBC 2.34
+| Red Hat Enterprise Linux (RHEL) | 9 | GLIBC 2.34
+| Oracle Linux | 9 | GLIBC 2.34
+|===
 
-`alpine-3.17`::
-This container is based on Alpine Linux 3.17 (`musl`), offering a smaller image
-size. Suitable for those who prefer a minimalistic approach.
+=== `alpine-3.17`
 
-Containers are tailored for Tebako packaging, featuring preinstalled Ruby
-environments versions 3.2.6 and 3.3.6.
+This container is based on **Alpine Linux 3.17**, offering an environment for packaging applications for systems that use the https://musl.libc.org[`musl` implementation of the C standard library].
 
-Both acontainers are available on the GitHub Container Registry (GHCR) for amd64 and arm64 architectures.
+Both containers are available on the **GitHub Container Registry (GHCR)** for **x86_64 (amd64)** and **aarch64 (arm64)** architectures, with multi-architecture manifests. These containers come preinstalled with Tebako packaging environments for Ruby versions **3.2.6** and **3.3.6**.
 
-== Using the Tebako containers
+== Using the Tebako Containers
 
 === General
 
-There are two primary methods for packaging with Tebako: from inside the
-container and from outside using Docker commands.
+There are two primary methods for packaging with Tebako:
 
-=== Prerequisites
-
-* Docker installed on your machine.
-* A Ruby application ready for packaging.
+1. **From outside the container**: Using Docker commands to package your application without entering the container.
+2. **From inside the container**: Interactively working within the container to package your application.
 
+=== Prerequisites
 
-=== Package using an ephemeral container
+- Docker installed on your machine.
+- A Ruby application ready for packaging.
 
-You can also package your application from outside the container by running a
-single Docker command.
+=== From Outside the Container
 
-This command mounts your workspace into the container and runs the
-`tebako press` command, specifying:
+You can package your application from outside the container by running a single Docker command. This command mounts your workspace into the container and executes the `tebako press` command, specifying:
 
-* application root
-* entry point
-* output location
-* Ruby version
+- Application root
+- Entry point
+- Output location
+- Ruby version
 
 [source,sh]
 ----
@@ -75,11 +74,10 @@ $ docker run -v <application_folder>:/mnt/w \
   tebako press <tebako press parameters>
 ----
 
-.Packaging `fontist` with an ephemeral container
+.Packaging the `fontist` Gem from Outside the Container
 [example]
 ====
-A Ruby application called `fontist` inside `fontist/` under the current
-directory, can be packaged into `./fontist-package` using the following command.
+To package the https://github.com/fontists/fontist[`fontist` gem], a Ruby application for managing fonts, located in the `fontist/` directory under the current working directory, use the following command:
 
 [source,sh]
 ----
@@ -89,11 +87,11 @@ docker run -v $PWD:/mnt/w \
 ----
 ====
 
-=== Package using a persistent container
+=== From Inside the Container
 
 To package your application from inside the Tebako container, follow these steps:
 
-. Pull the Tebako container image:
+1. Pull the Tebako container image:
 +
 [source,sh]
 ----
@@ -102,40 +100,50 @@ $ docker pull ghcr.io/tamatebako/tebako-<container_tag>:latest
 +
 Replace `<container_tag>` with the desired container tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
 
-. Start and enter the container interactively:
+2. Start and enter the container interactively:
 +
 [source,sh]
 ----
 $ docker run -it --rm -v <application_folder>:/mnt/w ghcr.io/tamatebako/tebako-<container_tag>:latest bash
 ----
 +
-Replace `<container_tag>` with the appropriate tag and `<application_folder>`
-with the path to your application folder.
+Replace `<container_tag>` with the appropriate tag and `<application_folder>` with the path to your application folder.
 
-. Once inside, run the `tebako press` command:
+3. Once inside the container, run the `tebako press` command:
 +
 [source,sh]
 ----
 $ tebako press <tebako press parameters>
 ----
 
-
-.Packaging `fontist` with a persistent container
+.Packaging the `fontist` Gem from Inside the Container
 [example]
 ====
-A Ruby application called `fontist` inside `fontist/` under the current
-directory, can be packaged into `./fontist-package` using the following command.
+To package the https://github.com/fontists/fontist[`fontist` gem], located in the `fontist/` directory under the current working directory, use the following commands:
 
 [source,sh]
 ----
-# Starting a persistent container
+# Start and enter the container
 $ docker run -it --rm -v $PWD:/mnt/w ghcr.io/tamatebako/tebako-<container_tag>:latest bash
 
 # Run this after entering the container
 $ tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.6
 ----
 ====
 
+`Gemspec` files often specify the files included in the gem using `git ls-files`. When packaging from inside the container, the container's instance of `git` will be used to resolve these files.
+
+If you use a mounted host directory for packaging, the container's instance of `git` will not have access to it by default. To resolve this, you must alter the container's configuration by running the following command before packaging:
+
+[source,sh]
+----
+git config --global --add safe.directory <source>
+----
+
+However, to avoid this additional setup, we recommend packaging **from outside the container** instead of modifying the container's configuration as described above.
+
+Packaging from inside the container is primarily designed to support CI environments like GitHub Actions (GHA) or Cirrus CI. It provides a complete packaging environment that
+does not require any additional installations, making it ideal for automated workflows.
 
 == License