Merge pull request 'Rename the wiki pages without hyphens' (#80) from rename-wiki-pages-no-hyphens into main

Reviewed-on: #80

.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

.gitea/workflows/quality.yml

@@ -0,0 +1,23 @@
+name: Quality
+
+# Calls the shared quality-check workflow of TirSystem/github-action
+# (contract: ADR-0005 there). It runs shellcheck and shfmt on the tracked
+# shell files and changes no file. Configuration comes from .shellcheckrc
+# and .editorconfig in this repository. 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
+    # Pinned to an exact tag, never to main; tools-ref pins the script to the
+    # same tag, so the whole check is fixed.
+    uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1.1.0
+    with:
+      languages: shell
+      tools-ref: v1.1.0

.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 (push)"
+        run: python3 shared-scripts/tools/release.py

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.

README.md

@@ -52,8 +52,8 @@ Requirements:
 | `jq` (optional) | JSON parsing; without it a small built-in reader is used |
 
 ```bash
-git clone https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry.git
+git clone https://git.tirsystem.com/TirSystem-BashScript/repo-foundry.git
-cd RepoFoundry
+cd repo-foundry
 src/create-project.sh --help
 ```
 
@@ -69,7 +69,7 @@ command (below):
 
 ```bash
 cd ~/work                                  # the folder that will hold my-app
-~/src/RepoFoundry/src/create-project.sh    # creates ~/work/my-app
+~/src/repo-foundry/src/create-project.sh    # creates ~/work/my-app
 ```
 
 ### Make it a global command
@@ -104,7 +104,7 @@ run `export MSYS=winsymlinks:nativestrict` before the `ln -s`, or use an alias
 in `~/.bashrc`, which works because the script finds its own folder:
 
 ```bash
-alias repo-foundry='bash /c/Users/me/RepoFoundry/src/create-project.sh'
+alias repo-foundry='bash /c/Users/me/repo-foundry/src/create-project.sh'
 ```
 
 ## Configuration

wiki/GettingStarted.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/repo-foundry.git
+cd repo-foundry
+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](SshAndTokens)). `.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`.

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](GettingStarted) | Requirements, install and the first run |
+| [SSH and tokens](SshAndTokens) | 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/repo-foundry/src/branch/main/README.md).
+Report a problem as an [issue](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/issues).

wiki/SshAndTokens.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/repo-foundry/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/repo-foundry/src/branch/main/howto/create-access-tokens.md). The exact permissions are under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) in the README.

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](SshAndTokens) |
+| 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/repo-foundry/src/branch/main/README.md#error-handling-and-recovery) and [Known limitations](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#known-limitations) in the README.

wiki/_Sidebar.md

@@ -0,0 +1,4 @@
+- [Home](Home)
+- [Getting started](GettingStarted)
+- [SSH and tokens](SshAndTokens)
+- [Troubleshooting](Troubleshooting)