From 88eac336022b2d6f307b329d4e92f335b2d54156 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Mon, 12 Oct 2026 00:32:06 +0800 Subject: [PATCH] Add the wiki, Quality and Release workflows Add a wiki/ folder with a .publish marker for the shared Publish wiki workflow, a Quality workflow (shellcheck and shfmt through the shared reusable workflow) and a manual Release workflow that builds the release page from CHANGELOG.md. Set switch_case_indent for *.sh in .editorconfig so shfmt accepts the existing case layout. --- .editorconfig | 3 ++ .gitea/workflows/quality.yml | 20 +++++++++++++ .gitea/workflows/release.yml | 56 ++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 23 +++++++++++++++ wiki/.publish | 0 wiki/Getting-started.md | 36 +++++++++++++++++++++++ wiki/Home.md | 20 +++++++++++++ wiki/SSH-and-tokens.md | 25 ++++++++++++++++ wiki/Troubleshooting.md | 10 +++++++ wiki/_Sidebar.md | 4 +++ 10 files changed, 197 insertions(+) create mode 100644 .gitea/workflows/quality.yml create mode 100644 .gitea/workflows/release.yml create mode 100644 CHANGELOG.md create mode 100644 wiki/.publish create mode 100644 wiki/Getting-started.md create mode 100644 wiki/Home.md create mode 100644 wiki/SSH-and-tokens.md create mode 100644 wiki/Troubleshooting.md create mode 100644 wiki/_Sidebar.md diff --git a/.editorconfig b/.editorconfig index 8484116..6606c67 100644 --- a/.editorconfig +++ b/.editorconfig @@ -7,3 +7,6 @@ end_of_line = lf insert_final_newline = true charset = utf-8 trim_trailing_whitespace = true + +[*.sh] +switch_case_indent = true diff --git a/.gitea/workflows/quality.yml b/.gitea/workflows/quality.yml new file mode 100644 index 0000000..a1028d5 --- /dev/null +++ b/.gitea/workflows/quality.yml @@ -0,0 +1,20 @@ +name: Quality + +# Shell checks (shellcheck, shfmt) with the shared reusable workflow of +# TirSystem/github-action. It changes no file and needs no secret. The release +# workflow requires this run to be green on the commit it releases. +on: + pull_request: + push: + branches: [ main ] + workflow_dispatch: + +jobs: + quality: + permissions: + contents: read + uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1.1.0 + with: + languages: shell + # Pinned to the same tag as the workflow, so the whole check is fixed. + tools-ref: v1.1.0 diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml new file mode 100644 index 0000000..0cc4fb4 --- /dev/null +++ b/.gitea/workflows/release.yml @@ -0,0 +1,56 @@ +name: Release + +# Releases this repository: creates the version tag and the release page from +# the CHANGELOG.md entry, and only when the commit is the tip of main, its +# Quality run is green and the changelog has an entry for the version. The +# script is a file of TirSystem/github-action (tools/release.py), fetched at an +# exact tag. dry_run defaults to true: it checks and prints and writes nothing, +# so a release is a deliberate second run with dry_run false. +# +# release.py also keeps a moving major tag (v0 for 0.x versions) pointing to +# the highest release of its major version, as in TirSystem/github-action. +on: + workflow_dispatch: + inputs: + version: + description: "Version to release, MAJOR.MINOR.PATCH without a leading v" + required: true + dry_run: + description: "true checks only; false creates the tag and the release page" + required: false + default: "true" + +concurrency: + group: release + cancel-in-progress: false + +jobs: + release: + permissions: + contents: write + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Check out the repository + uses: actions/checkout@v4.2.2 + + - name: Fetch the shared script + uses: actions/checkout@v4.2.2 + with: + repository: TirSystem/github-action + ref: v1.1.0 + path: shared-scripts + + - name: Check and publish the release + env: + GITEA_API_URL: ${{ gitea.api_url }} + SOURCE_REPOSITORY: ${{ gitea.repository }} + RELEASE_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_RELEASE || github.token }} + RELEASE_VERSION: ${{ inputs.version }} + RELEASE_DRY_RUN: ${{ inputs.dry_run }} + RELEASE_SHA: ${{ gitea.sha }} + # The status context of the Quality run on the commit. Check the exact + # text on a pull request and correct it here if the dry run says the + # run was not found. + VALIDATION_CONTEXT: "Quality / quality / quality-checks (push)" + run: python3 shared-scripts/tools/release.py diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..cbc6d90 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog + +All notable changes to RepoFoundry. Versions are tags `vMAJOR.MINOR.PATCH`. +The release workflow takes the text of a release page from the entry of its +version, so every release needs an entry here before it is started. + +Each release lists its changes in these groups, in this order: **Breaking**, +**Added**, **Changed**, **Fixed**. A release with a Breaking entry has a new +major version. + +`python tools/changelog.py check` of `TirSystem/github-action` verifies this +file. + +## [Unreleased] + +### Added + +- Gitea workflows: Quality (shellcheck and shfmt through the shared reusable + workflow) and Release (tag and release page from this changelog). +- A `wiki/` folder with a `.publish` marker, published to the Gitea wiki by the + shared Publish wiki workflow. +- `switch_case_indent` for `*.sh` in `.editorconfig`, so `shfmt` accepts the + existing layout of `case` branches. diff --git a/wiki/.publish b/wiki/.publish new file mode 100644 index 0000000..e69de29 diff --git a/wiki/Getting-started.md b/wiki/Getting-started.md new file mode 100644 index 0000000..5972cec --- /dev/null +++ b/wiki/Getting-started.md @@ -0,0 +1,36 @@ +# Getting started + +## Requirements + +| Tool | Needed for | +| --- | --- | +| bash 4.4 or later | the script (macOS ships 3.2: install a newer bash first) | +| `git` | the local project and the framework submodule | +| `curl` | the GitHub and Gitea APIs | +| `ssh` (optional) | the SSH check; without it the framework steps are skipped | +| `jq` (optional) | JSON parsing; without it a small built-in reader is used | + +## Install + +```bash +git clone https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry.git +cd RepoFoundry +src/create-project.sh --help +``` + +Nothing is installed system-wide: the script runs from the checkout. + +## Configure + +Copy `config.env.example` to `config.env` and `.env.example` to `.env`, then set the service addresses and the tokens (see [SSH and tokens](SSH-and-tokens)). `.env` holds credentials and is never committed. + +## Run + +Start the script from the folder that should hold the new project: + +```bash +src/create-project.sh # dry run: reads from the hosts, creates nothing +src/create-project.sh --apply # creates everything after a final yes +``` + +No commit is made in the new project. Work on a branch there: the framework's hooks refuse commits on `main`. diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000..70e5cda --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,20 @@ +# Repo Foundry + +Repo Foundry (`src/create-project.sh`) sets up a new project in one run: + +- a **Gitea** repository, the source of truth; +- optionally an empty **GitHub** repository that receives everything through a push mirror from Gitea; +- a **local project** with one credential-free remote, `origin`, and the SQA-QC-Framework as a git submodule, with its skills, git hooks and templates installed. + +It is a Bash script. It shows a plan first and creates nothing until you pass `--apply` and answer yes. + +## Pages + +| Page | What it covers | +| --- | --- | +| [Getting started](Getting-started) | Requirements, install and the first run | +| [SSH and tokens](SSH-and-tokens) | SSH access to Gitea and the two access tokens | +| [Troubleshooting](Troubleshooting) | Common failures and what to do | + +The full reference (configuration files, security decisions, error handling, known limitations) is the [README](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md). +Report a problem as an [issue](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/issues). diff --git a/wiki/SSH-and-tokens.md b/wiki/SSH-and-tokens.md new file mode 100644 index 0000000..41c1d60 --- /dev/null +++ b/wiki/SSH-and-tokens.md @@ -0,0 +1,25 @@ +# SSH and tokens + +## SSH access to Gitea + +The framework submodule is fetched over SSH on port **10022**. Before you run the script: + +1. Add your SSH public key to your Gitea account. +2. Connect once by hand so the server's host key is known (the script refuses unknown host keys): + + ```bash + ssh -p 10022 -T git@git.tirsystem.com + ``` + + A message that you have successfully authenticated, without shell access, means it works. + +> **Passphrase keys.** The script never prompts for a passphrase. A key with a passphrase must already be loaded in `ssh-agent` (`ssh-add`). This is tracked in [issue 77](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/issues/77). + +## Tokens + +| Token | Key in `.env` | Needed | Type | +| --- | --- | --- | --- | +| Gitea access token | `GITEA_TOKEN` | always | access token with scopes | +| GitHub personal access token | `GITHUB_PAT` | only when you choose GitHub | **classic** personal access token | + +Step by step with pictures: [how to create the access tokens](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/howto/create-access-tokens.md). The exact permissions are under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md#token-permissions) in the README. diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md new file mode 100644 index 0000000..475f196 --- /dev/null +++ b/wiki/Troubleshooting.md @@ -0,0 +1,10 @@ +# Troubleshooting + +| Symptom | What to check | +| --- | --- | +| The plan says the SSH test failed | Your key is in your Gitea account, the host key is known (`ssh -p 10022 -T git@git.tirsystem.com`), and a passphrase key is loaded with `ssh-add` | +| The script stops at the tool check | bash is 4.4 or later, and `git` and `curl` are installed | +| A host rejects the token | The token is current and has the scopes in [SSH and tokens](SSH-and-tokens) | +| A run stopped half way | Fix the cause and run the same command again with `--apply`: what was already created is offered for reuse | + +More: [Error handling and recovery](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md#error-handling-and-recovery) and [Known limitations](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md#known-limitations) in the README. diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md new file mode 100644 index 0000000..e480d59 --- /dev/null +++ b/wiki/_Sidebar.md @@ -0,0 +1,4 @@ +- [Home](Home) +- [Getting started](Getting-started) +- [SSH and tokens](SSH-and-tokens) +- [Troubleshooting](Troubleshooting)