diff --git a/.github/labels.md b/.github/labels.md new file mode 100644 index 0000000..35927b0 --- /dev/null +++ b/.github/labels.md @@ -0,0 +1,20 @@ +# Repository Labels + +This repository currently uses the default GitHub label baseline: + +- `bug` +- `documentation` +- `duplicate` +- `enhancement` +- `good first issue` +- `help wanted` +- `invalid` +- `question` +- `wontfix` + +## Governance Notes + +- These labels were confirmed via `gh label list` on 2026-05-27. +- If labels change in the GitHub UI, update this file in the same change so the tracked baseline stays in sync. +- GitHub branch protection is not currently available for this private repository tier. The GitHub API returns `403 Upgrade to GitHub Pro or make this repository public` when querying branch-protection settings for `main`. +- Until that changes, repository discipline depends on review, CI, and explicit git staging rather than platform-enforced protection rules. diff --git a/.github/workflows/repo-hygiene.yml b/.github/workflows/repo-hygiene.yml new file mode 100644 index 0000000..cd987a0 --- /dev/null +++ b/.github/workflows/repo-hygiene.yml @@ -0,0 +1,52 @@ +name: Repository Hygiene + +on: + push: + branches: + - main + pull_request: + +jobs: + hygiene: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Lint markdown + run: npx --yes markdownlint-cli@0.45.0 "**/*.md" --ignore node_modules + + - name: Validate JSON files + run: | + set -e + # jq and ruby are provided by the ubuntu-latest runner image. + while IFS= read -r -d '' file; do + jq empty "$file" + done < <(find . -path './.git' -prune -o -name '*.json' -print0) + + - name: Validate YAML files + run: | + set -e + # jq and ruby are provided by the ubuntu-latest runner image. + while IFS= read -r -d '' file; do + ruby -e 'require "yaml"; YAML.load_file(ARGV[0])' "$file" + done < <(find . -path './.git' -prune -o \( -name '*.yml' -o -name '*.yaml' \) -print0) + + - name: Verify ignored UI and resource patterns + shell: bash + run: | + set -e + # This step relies on Bash 4+ array syntax available on ubuntu-latest. + samples=(sample.dfm sample.res sample.ico sample.dcu TalkEd.exe) + expected=${#samples[@]} + actual=$(printf '%s\n' "${samples[@]}" | (git check-ignore --stdin || true) | wc -l) + if [ "$actual" -ne "$expected" ]; then + echo "Expected $expected ignored artifact matches, found $actual" + exit 1 + fi \ No newline at end of file diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..b077f0e --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,4 @@ +{ + "default": true, + "MD013": false +} diff --git a/BUILDING.md b/BUILDING.md index 0804516..efb7153 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -5,9 +5,9 @@ TalkEd is a classic Delphi 7 VCL application. The authoritative source build surface is: - project file: `TLKEdit.dpr` -- compiler options: `TLKEdit.cfg` +- local compiler options file: `TLKEdit.cfg` when present in a native Delphi worktree - IDE project options: `TLKEdit.dof` -- Windows resource file: `TLKEdit.res` +- local Windows resource file: `TLKEdit.res` when present in a native Delphi worktree ## What Works Today @@ -21,6 +21,14 @@ Expected flow: 2. Ensure the companion units and forms are present in the same repository root. 3. Build the project to produce `TalkEd.exe`. +Note that some native Delphi companion files are intentionally untracked in git. A Windows build environment may still need locally generated or locally maintained files such as `TLKEdit.cfg`, `TLKEdit.res`, `.dfm`, and icon resources. + +If one of those files is missing: + +1. let Delphi regenerate `TLKEdit.cfg` from the project when possible, +2. regenerate `TLKEdit.res` from the IDE project resource settings or copy it from a known-good Windows worktree, +3. stop and recover missing `.dfm` or other form/resource files from a trusted historical checkout rather than recreating them by guesswork. + ### Command-Line Build The VS Code task surface assumes a Delphi command-line compiler such as `dcc32.exe` on Windows. @@ -42,7 +50,6 @@ The VS Code launch surface includes: ## What Does Not Exist Yet -- No modern CI pipeline. - No repeatable non-Windows source build. - No FPC/Lazarus project file checked into this repository. - No automated packaging step. @@ -50,9 +57,7 @@ The VS Code launch surface includes: ## Important Files for Build Success - `TLKEdit.dpr` -- `TLKEdit.cfg` - `TLKEdit.dof` -- `TLKEdit.res` - `UMainForm.pas` - `UTLKFile.pas` - `USearchForm.pas` @@ -63,7 +68,7 @@ The VS Code launch surface includes: ## Compiler Notes -`TLKEdit.cfg` shows this project was configured with Delphi-era compiler directives and paths. Those settings should be treated as historical build inputs rather than modernized defaults. +If a local `TLKEdit.cfg` file is present, it reflects Delphi-era compiler directives and machine-specific paths. Treat it as a local historical build input rather than a portable repository contract. In particular: @@ -95,3 +100,5 @@ The repository ships workspace tasks for: - launching the built executable. These tasks are convenience tooling only. They do not replace real runtime verification against TLK files. + +The repository also ships a GitHub Actions workflow for markdown, JSON, YAML, and ignore-policy hygiene. That workflow is a repository-health check, not a Delphi build. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ee4f4c..6625f53 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,10 @@ This repository contains the classic Delphi 7 TalkEd source tree and workspace s Non-Windows environments are suitable for workspace maintenance, documentation, and launch-flow validation, but not authoritative source compilation. +Branch protection is not currently available for this private repository tier. Contributors should therefore treat PR review, CI status, and careful staging as the practical enforcement layer. +That also means accidental direct pushes are easier than they should be on a protected repository. Prefer feature branches and PR-based review even for small changes, and double-check CI status before merging. +If a direct push to `main` happens by mistake, do not rewrite history casually. Notify the other contributors, open a follow-up corrective PR if needed, and prefer an explicit revert or fix-forward commit over a force-push. + ## Contribution Priorities Prioritize changes in this order: @@ -84,6 +88,7 @@ If the change touches ignored files such as `.dfm`, `.res`, or `.ico`, call that The current repository policy ignores several Delphi-era binary or designer artifacts, including: - `.dcu` +- `.cfg` - `.dfm` - `.ddp` - `.res` @@ -93,10 +98,12 @@ The current repository policy ignores several Delphi-era binary or designer arti That means: - pure form-designer changes may not show up in git status, +- local compiler-option files may exist on disk without being committed, - resource or icon changes are not tracked automatically, - a contributor may need a deliberate repository policy change before certain visual updates can be reviewed properly. Do not silently rely on ignored artifacts for a functional fix. +Do not rely on untracked local compiler settings for reproducible build guidance either; if a setting matters to future contributors, document it in tracked markdown rather than assuming a local `TLKEdit.cfg` will be present. ## Code Review Expectations diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 3cc4bdf..f9a433d 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -25,6 +25,14 @@ Ignored by current policy include: When making a change that depends on one of those files, document the limitation instead of pretending it is tracked. +`TLKEdit.cfg` is intentionally ignored because the local file in a Delphi environment can contain machine-specific paths. Repository docs should describe it as a local companion file, not as a guaranteed tracked artifact. +If a local compiler or library setting matters to reproducible work, capture that requirement in tracked documentation instead of assuming contributors will share the same untracked `TLKEdit.cfg` contents. +When such a setting matters, use this checklist: + +1. add the requirement to `BUILDING.md` or `CONTRIBUTING.md`, +2. mention it in the PR summary or change notes for the affected work, +3. avoid copying machine-specific absolute paths or user-specific IDE state into tracked files. + ## Naming Conventions ### Units @@ -89,6 +97,13 @@ When editing one of those units, preserve the header style. If you add meaningfu - Build tasks should point at `TLKEdit.dpr`. - Launch tasks should assume `TalkEd.exe` and optional `.tlk` startup arguments. - Non-Windows launch support is convenience tooling via Wine, not a statement of native build parity. +- GitHub Actions checks should stay repository-portable and must not imply Delphi source-build support where none exists. + +## Repository Governance + +- Default GitHub labels may be configured and documented in tracked repo files. +- Do not claim branch protection is enabled unless the GitHub API confirms it. +- For this repository at present, branch protection should be documented as blocked by repository plan limits rather than represented as active policy. ## Change Discipline diff --git a/README.md b/README.md index 0e5975a..e4afea2 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ TalkEd is a Delphi 7 desktop editor for BioWare-style `TLK V3.0` talk table files. In practice, this repository is aimed at Knights of the Old Republic modding workflows where a `.tlk` file acts as a string database keyed by `StrRef` values. +This is the **authentic** source code Stoffe was working with 10-20 years ago, released to the community so it can be maintained and kept from becoming abandonware. + The application lets you: - open an existing `.tlk` file from the UI or from the command line, @@ -26,7 +28,7 @@ The application lets you: Top-level files are intentionally flat and mirror the original Delphi 7 project structure. - `TLKEdit.dpr`: VCL application entrypoint and startup wiring. -- `TLKEdit.cfg`: compiler switches used by the Delphi command-line build. +- `TLKEdit.cfg`: local Delphi compiler options file that may exist in a native build environment but is intentionally not tracked in git. - `TLKEdit.dof`: Delphi IDE project options. - `UTLKFile.pas`: TLK parsing, in-memory string storage, and save logic. - `UMainForm.pas`: main window, menus, grid display, and orchestration. @@ -115,6 +117,8 @@ The repository does not contain an automated cross-platform build. On Linux and See `BUILDING.md` for the full build and launch workflow. +Local Delphi companion files such as `TLKEdit.cfg`, `.dfm`, `.res`, and icon resources may exist in a native Windows worktree, but this repository intentionally does not commit those UI/resource artifacts today. + ## Current Workspace Support The `.vscode` folder is tuned to this repository and includes: @@ -131,6 +135,8 @@ The `.vscode` folder is tuned to this repository and includes: - Build validation is currently manual and environment-dependent. - The repository `.gitignore` excludes `.dfm`, `.res`, `.ico`, `.ddp`, and generated binaries, which means some visual/resource changes are not tracked unless that policy is changed intentionally. - The TLK reader/writer explicitly carries fixes for long strings beyond the original 4096-byte buffer behavior, but this remains an area worth validating when changing TLK serialization. +- GitHub branch protection is not currently enforceable on this private repository tier; the GitHub API returns `403 Upgrade to GitHub Pro or make this repository public` for that setting. +- Contributor workflow expectations for that limitation live in `CONTRIBUTING.md`. ## Documentation Map @@ -139,6 +145,7 @@ The `.vscode` folder is tuned to this repository and includes: - `ARCHITECTURE.md`: unit and workflow breakdown. - `CONTRIBUTING.md`: contribution process and validation expectations. - `CONVENTIONS.md`: coding and repository conventions specific to this project. +- `.github/labels.md`: current repository label baseline and governance notes. ## Repository Remote diff --git a/docs/plans/2026-05-27-repo-hardening-plan.md b/docs/plans/2026-05-27-repo-hardening-plan.md new file mode 100644 index 0000000..431a345 --- /dev/null +++ b/docs/plans/2026-05-27-repo-hardening-plan.md @@ -0,0 +1,150 @@ +--- +title: TalkEd Repo Hardening Plan +date: 2026-05-27 +status: active +--- + +## Overview + +## Problem Frame + +The repository bootstrap landed source, docs, and VS Code support, but it still has three gaps that affect maintainability and team workflow: + +1. Source-vs-repo parity is imperfect because repository docs still talk about some local Delphi companion artifacts as if they are committed, while the current ignore policy intentionally excludes several of them. +2. The repository has no CI guardrail for markdown, JSON, YAML, or ignore-policy drift. +3. Governance hardening is incomplete: default labels exist, but branch protection cannot currently be enabled on this private repository because GitHub returns a 403 for this feature tier. + +## Scope Boundaries + +In scope: + +- Make the repository docs accurately reflect tracked versus intentionally ignored Delphi-era artifacts. +- Add lightweight GitHub Actions checks that are valid for this repository without requiring Delphi builds. +- Add a small amount of repository governance metadata where it is clearly useful and low-risk. +- Document the branch-protection platform limitation rather than pretending it is configured. + +Out of scope: + +- Native Delphi build automation. +- Tracking `.dfm`, `.res`, `.ico`, `.dcu`, or built executables. +- Reworking the Pascal source structure. +- UI or resource-file changes. + +## Key Technical Decisions + +- Keep the current policy of excluding UI/resource artifacts from git. This matches the explicit user instruction for this session. +- Treat `TLKEdit.cfg` as a local build artifact rather than a committed source file. The existing file contains machine-specific paths, so documentation should describe it as a local companion file rather than as a guaranteed tracked file. +- Use GitHub Actions only for repository-hygiene checks that do not depend on Delphi toolchains. +- Treat branch protection as a documented external blocker because the GitHub API returns `403 Upgrade to GitHub Pro or make this repository public` for this repository. + +## Implementation Units + +### U1: Align docs with tracked-artifact reality + +Goal: +Make repository-facing docs accurately describe which Delphi files are committed, which are local-only, and which are intentionally ignored. + +Files: + +- Modify `README.md` +- Modify `BUILDING.md` +- Modify `CONTRIBUTING.md` +- Modify `CONVENTIONS.md` + +Approach: + +- Remove or reword any implication that `TLKEdit.cfg`, `.dfm`, `.res`, `.ico`, or similar ignored artifacts are part of the committed repository surface. +- Clarify that some files may be required locally for native Delphi work even when they are intentionally absent from git. +- Add a short note about branch-protection unavailability in the governance-facing docs if helpful. + +Patterns to follow: + +- Keep the same concise, repository-grounded style already established in the new markdown files. + +Test scenarios: + +- Happy path: all updated docs read consistently and no section contradicts the ignore policy. +- Edge case: docs distinguish “exists locally” from “committed to repo”. +- Error path: no markdown lint regressions. + +Verification: + +- Markdown diagnostics clean for touched files. + +### U2: Add repository-hygiene CI + +Goal: +Add a GitHub Actions workflow that validates repository-health artifacts that are portable across environments. + +Files: + +- Create `.github/workflows/repo-hygiene.yml` + +Approach: + +- Run markdown lint across repository docs. +- Validate JSON files parse. +- Validate YAML files parse. +- Assert representative UI/resource artifact names still match the intended ignore policy. + +Patterns to follow: + +- Keep workflow simple, dependency-light, and independent from Delphi toolchains. + +Test scenarios: + +- Happy path: workflow file parses and targets push/pull_request. +- Edge case: ignore-policy check uses path patterns that do not require the ignored files to exist in CI. +- Error path: malformed markdown/json/yaml would fail deterministically. + +Verification: + +- YAML diagnostics clean. +- Review workflow contents for deterministic failure signals. + +### U3: Add minimal governance metadata + +Goal: +Capture the remaining governance state in tracked repo files so collaborators understand what is configured and what is blocked externally. + +Files: + +- Create `.github/labels.md` +- Optionally modify `README.md` or `CONTRIBUTING.md` if cross-references are useful + +Approach: + +- Record the working default-label set observed via `gh label list`. +- Record that branch protection is currently blocked by GitHub plan limits on this private repo. +- Avoid fake configuration files that imply protections are active when they are not. + +Patterns to follow: + +- Prefer factual, operational documentation over speculative governance prose. + +Test scenarios: + +- Happy path: governance doc states current label baseline and branch-protection blocker clearly. +- Edge case: wording does not imply branch protection has been enabled. +- Error path: markdown diagnostics remain clean. + +Verification: + +- Markdown diagnostics clean for touched files. + +## Dependencies and Sequence + +1. U1 first so the docs reflect the actual repository state before adding new automation. +2. U2 second because CI should validate the corrected docs and metadata. +3. U3 last so the governance note reflects the final repository-hygiene setup and current GitHub platform constraint. + +## Risks + +- Overstating what is committed versus what exists locally would recreate the current parity problem. +- A CI workflow that depends on unavailable tooling would become noise instead of a guardrail. +- Governance documentation could accidentally imply that branch protection is configured when it is not. + +## Deferred To Implementation + +- Choose the simplest workflow dependencies available on `ubuntu-latest` without adding repository package manifests just for linting. +- Decide whether the governance note belongs best in a dedicated `.github/labels.md` file or in existing docs after reading the final markdown edits together.