Skip to content

Commit d00cfc9

Browse files
committed
docs: add contributing guide and onboarding helper scripts (issue #68)
1 parent d4f1454 commit d00cfc9

File tree

5 files changed

+192
-0
lines changed

5 files changed

+192
-0
lines changed

CONTRIBUTING.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Contributing to Veraison Documentation
2+
3+
Thank you for your interest in contributing to the Veraison docs. This file gives a
4+
lightweight, focused workflow that helps maintainers review contributions quickly and
5+
ensures a consistent developer experience.
6+
7+
Steps
8+
1. Fork the repository and create a branch named `docs/issue-<number>-<short-desc>`.
9+
2. Make small, focused commits. Prefer one logical change per commit.
10+
3. Run the provided scripts in `scripts/` to validate your environment and examples.
11+
- `scripts/setup.sh` to install developer prerequisites (non-destructive; prompts before changes).
12+
- `scripts/validate-setup.sh` to run pre-flight checks.
13+
- `scripts/quick-start.sh` to run a minimal local demo (requires Docker).
14+
4. Update or add documentation under the appropriate folder (e.g., `api/`, `demo/`, `architecture/`).
15+
5. Add tests or checks where appropriate (examples validation, OpenAPI linting).
16+
6. Push your branch and open a Pull Request against `main` with the issue number in the title.
17+
18+
Pull Request Checklist
19+
- [ ] I followed the contributing guidelines in this file.
20+
- [ ] I ran `scripts/validate-setup.sh` and fixed any issues.
21+
- [ ] The changes are described clearly in the PR description.
22+
- [ ] If the change affects examples or code, I added or updated tests where applicable.
23+
24+
Notes
25+
- Keep changes minimal and avoid large refactors in the same PR.
26+
- If your change needs CI additions (workflows), open a separate PR for the CI work.
27+
28+
If you have questions, ask on the Veraison Zulip: https://veraison.zulipchat.com

README.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,33 @@
2525
* [DICE notes](musings/dice.md)
2626
* [Device and Supply-Chain Modelling](musings/device-and-supply-chain-modelling.md)
2727
* [Assumptions about Attestation Evidence](musings/token-assumptions.md)
28+
```
29+
30+
## Quick start
31+
32+
This repository includes small helper scripts to improve the developer onboarding experience
33+
and address common setup/validation tasks. They are intentionally conservative and
34+
platform-guided. See `CONTRIBUTING.md` for the recommended workflow.
35+
36+
1. Run a quick validation to check your environment:
37+
38+
```sh
39+
scripts/validate-setup.sh
40+
```
41+
42+
2. If tools are missing, either follow the printed suggestions or use the guided setup:
43+
44+
```sh
45+
scripts/setup.sh --dry-run
46+
# or
47+
scripts/setup.sh
48+
```
49+
50+
3. To run a minimal quick-start verification (requires Docker):
51+
52+
```sh
53+
scripts/quick-start.sh
54+
```
55+
56+
These scripts are small helpers to make developer onboarding easier. They don't replace
57+
per-demo instructions; please check `demo/` for demo-specific steps (PSA and CCA demos).

scripts/quick-start.sh

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#!/usr/bin/env bash
2+
# scripts/quick-start.sh - minimal quick start for local evaluation (requires Docker)
3+
set -euo pipefail
4+
5+
if ! command -v docker >/dev/null 2>&1; then
6+
echo "Docker is required for quick-start. Please install Docker or run 'scripts/setup.sh'"
7+
exit 2
8+
fi
9+
10+
echo "Starting a minimal quick-start environment using Docker."
11+
12+
echo "Pulling a small busybox image as a placeholder demo (no network services are required)."
13+
docker pull busybox:latest >/dev/null
14+
15+
echo "Running a quick command inside a short-lived container to verify Docker works."
16+
docker run --rm busybox:latest echo "Quick-start: docker run succeeded"
17+
18+
echo "Quick-start finished. This repository's demos require more specific images and compose files which
19+
should be added per-demo under 'demo/'. See demo/psa/ and demo/cca/ for example workflows."

scripts/setup.sh

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
#!/usr/bin/env bash
2+
# scripts/setup.sh - install minimal developer prerequisites (non-destructive)
3+
set -euo pipefail
4+
5+
usage(){
6+
cat <<EOF
7+
Usage: $(basename "$0") [--dry-run]
8+
9+
Installs or suggests installation steps for common developer dependencies used by the
10+
Veraison documentation (docker, docker-compose, protoc, shellcheck).
11+
This script is conservative: it prints commands and prompts before making changes.
12+
EOF
13+
}
14+
15+
DRY_RUN=0
16+
while [[ ${#} -gt 0 ]]; do
17+
case "$1" in
18+
--dry-run) DRY_RUN=1; shift;;
19+
-h|--help) usage; exit 0;;
20+
*) echo "Unknown arg: $1"; usage; exit 2;;
21+
esac
22+
done
23+
24+
echo "Checking common tools..."
25+
need_install=()
26+
check(){
27+
if ! command -v "$1" >/dev/null 2>&1; then
28+
need_install+=("$1")
29+
echo " - $1: MISSING"
30+
else
31+
echo " - $1: found ($(command -v "$1"))"
32+
fi
33+
}
34+
35+
check docker
36+
check docker-compose || check docker-compose
37+
check protoc
38+
check shellcheck
39+
40+
if [[ ${#need_install[@]} -eq 0 ]]; then
41+
echo "All common tools detected."
42+
exit 0
43+
fi
44+
45+
echo "\nTools suggested for install: ${need_install[*]}"
46+
if [[ $DRY_RUN -eq 1 ]]; then
47+
echo "Dry run: not installing anything."
48+
exit 0
49+
fi
50+
51+
read -r -p "Proceed with printed install suggestions? [y/N] " ans
52+
case "$ans" in
53+
[Yy]*) ;;
54+
*) echo "Aborting per user request."; exit 0;;
55+
esac
56+
57+
for t in "${need_install[@]}"; do
58+
echo "\nSuggested install for: $t"
59+
case "$t" in
60+
docker)
61+
cat <<'CMD'
62+
On Debian/Ubuntu:
63+
sudo apt-get update && sudo apt-get install -y ca-certificates curl gnupg lsb-release
64+
curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
65+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
66+
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io
67+
CMD
68+
;;
69+
docker-compose)
70+
cat <<'CMD'
71+
Install via pip (if using compose v1) or use Docker's compose plugin:
72+
python3 -m pip install --user docker-compose
73+
Or on modern systems:
74+
sudo apt-get install -y docker-compose-plugin
75+
CMD
76+
;;
77+
protoc)
78+
echo "Visit https://github.com/protocolbuffers/protobuf/releases and download a release for your OS. On debian/ubuntu: sudo apt-get install -y protobuf-compiler"
79+
;;
80+
shellcheck)
81+
echo "On Debian/Ubuntu: sudo apt-get install -y shellcheck"
82+
;;
83+
*)
84+
echo "No automated instruction for $t; please install it using your platform package manager."
85+
;;
86+
esac
87+
done
88+
89+
echo "\nSetup script finished. Re-run 'scripts/validate-setup.sh' to verify the environment."

scripts/validate-setup.sh

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
#!/usr/bin/env bash
2+
# scripts/validate-setup.sh - run pre-flight checks for documentation developer environment
3+
set -euo pipefail
4+
5+
echo "Running pre-flight checks for Veraison docs development environment"
6+
missing=0
7+
check(){
8+
if ! command -v "$1" >/dev/null 2>&1; then
9+
echo "[FAIL] Missing: $1"
10+
missing=1
11+
else
12+
echo "[ OK ] Found: $1 -> $(command -v "$1")"
13+
fi
14+
}
15+
16+
check docker
17+
check docker-compose || true
18+
check protoc || true
19+
check shellcheck || true
20+
21+
if [[ $missing -ne 0 ]]; then
22+
echo "One or more required tools are missing. Run scripts/setup.sh for guidance."
23+
exit 2
24+
fi
25+
26+
echo "All required tools appear installed."

0 commit comments

Comments
 (0)