diff --git a/README.md b/README.md index 3a36ed1..b6a3826 100644 --- a/README.md +++ b/README.md @@ -266,6 +266,8 @@ in focused files: - [`doc/cli.md`](doc/cli.md) describes the supported command-line interface. - [`doc/manifest-format.md`](doc/manifest-format.md) describes the manifest grammar and parser behavior. +- [`doc/examples/`](doc/examples/) contains small, release-specific starter + manifests. - [`doc/adr/`](doc/adr/) contains the project's Architecture Decision Records. - [`testing.md`](doc/testing.md) describes how to test the tool during development work. diff --git a/doc/examples/README.md b/doc/examples/README.md new file mode 100644 index 0000000..f30dcf1 --- /dev/null +++ b/doc/examples/README.md @@ -0,0 +1,36 @@ +# Example Manifests + +This directory contains small, release-specific starter manifests for +Bootstrap. The examples are intended to reduce the effort required to begin a +new workstation manifest without implying that every listed package is needed +on every system. + +Examples are organized by operating system, distribution, release, and +purpose: + +```text +doc/examples////.manifest +``` + +The initial example is: + +- [`linux/ubuntu/26.04/core.manifest`](linux/ubuntu/26.04/core.manifest), a + compact collection of generally useful command-line tools for Ubuntu 26.04. + +Treat each example as a starting point: + +- review the manifest before running it; +- add or remove packages to match the system's purpose; +- remember that package availability depends on configured repositories; and +- prefer unconstrained package names unless a genuine compatibility requirement + justifies a version constraint. + +Inspect an example without changing the system: + +```bash +./bootstrap.bash --dry-run --explain \ + doc/examples/linux/ubuntu/26.04/core.manifest +``` + +Additional purpose-specific manifests may be added alongside `core.manifest` +when a small, well-documented example would help users get started. diff --git a/doc/examples/linux/ubuntu/26.04/core.manifest b/doc/examples/linux/ubuntu/26.04/core.manifest new file mode 100644 index 0000000..0e4ef40 --- /dev/null +++ b/doc/examples/linux/ubuntu/26.04/core.manifest @@ -0,0 +1,22 @@ +#------------------------------------------------------------------------------ +# Ubuntu 26.04 core workstation example +# +# This manifest is a starting point for a small, generally useful collection +# of command-line tools. Review it before use and add or remove packages to +# match the system's purpose. +#------------------------------------------------------------------------------ + +# Version control and build tools +git +make + +# Download and transfer tools +curl +wget + +# Archive and compression tools +zip +unzip + +# HTTPS certificate roots +ca-certificates diff --git a/tests/examples.bats b/tests/examples.bats new file mode 100755 index 0000000..e0c9607 --- /dev/null +++ b/tests/examples.bats @@ -0,0 +1,22 @@ +#!/usr/bin/env bats + +load 'helpers' + +setup() { + REPO_ROOT="${BATS_TEST_DIRNAME}/.." + SCRIPT="${REPO_ROOT}/dist/bootstrap.bash" +} + +@test "example manifests are accepted by the manifest parser" { + example_count=0 + + while IFS= read -r manifest; do + example_count=$((example_count + 1)) + run bash -c "source '$SCRIPT'; bootstrap_manifest_parse_file '$manifest'" + + [ "$status" -eq 0 ] + [ -n "$output" ] + done < <(find "${REPO_ROOT}/doc/examples" -type f -name '*.manifest' -print | sort) + + [ "$example_count" -gt 0 ] +}