tendril/.github/decisions.md

Decisions — .github Directory

Last updated: 2025-01-27

Purpose

This document tracks decisions made about Gitea Actions workflows, automation, and the .github directory structure. Decisions are documented with context, rationale, and alternatives considered.

---

Decision Format

Each decision entry includes:

• Date: When the decision was made
• Context: What problem or need prompted this decision
• Decision: What was decided
• Rationale: Why this approach was chosen
• Alternatives: Other options considered
• Impact: What this affects

---

Decisions

[2025-01-27] Use Gitea Actions (not GitHub Actions)

Context: Repository is hosted on Gitea platform (self-hosted), not GitHub. Need to configure CI/CD automation for repository maintenance.

Decision: Use Gitea Actions with GitHub Actions compatibility.

Rationale:

• Gitea Actions uses the same YAML format as GitHub Actions
• Workflows are compatible and can be migrated seamlessly
• Same .github/workflows/ directory structure
• Familiar syntax for developers
• No need to learn a different workflow system

Alternatives Considered:

• Use GitHub Actions (not possible - repository is on Gitea)
• Use external CI/CD service (adds complexity, external dependency)
• Manual automation (not scalable, error-prone)

Impact:

• All workflows use .github/workflows/ structure
• Workflows use standard GitHub Actions YAML format
• Documentation references "Gitea Actions" with compatibility notes
• Workflows can be tested and run on Gitea platform

---

[2025-01-27] Automate KB Index Updates

Context: KB index (kb/_index.md) must stay current with KB files. Manual updates are error-prone and easy to forget.

Decision: Auto-update index on push to main branch when KB files change.

Rationale:

• Reduces manual maintenance burden
• Ensures index always reflects current KB state
• Prevents index from becoming stale
• Automated process is more reliable than manual updates
• Index generation script already exists and works

Alternatives Considered:

• Manual index updates (error-prone, easy to forget)
• Update on every push (too frequent, unnecessary commits)
• Scheduled updates (may miss recent changes)

Impact:

• Index is automatically updated when KB files are added/modified on main
• Requires contents: write permission for workflow
• Creates automatic commits with index updates
• Index always reflects current KB state

---

[2025-01-27] Validate KB Files in CI

Context: KB files must follow strict naming and frontmatter rules. Invalid files break the KB system and cause index generation to fail.

Decision: Validate KB files on push and pull requests when KB files change.

Rationale:

• Catch errors early before they reach main branch
• Maintain KB system integrity
• Prevent invalid files from breaking index generation
• Provide clear error messages for developers
• Enforce KB file standards automatically

Alternatives Considered:

• Manual validation (error-prone, easy to miss)
• Validate only on main branch (errors caught too late)
• No validation (system breaks with invalid files)

Impact:

• Invalid KB files block commits
• Developers get immediate feedback on errors
• KB system maintains high quality standards
• Requires contents: read permission for workflow

---

Future Decisions

Decisions about new workflows, automation changes, or .github structure modifications should be added here with the same format.

---

Location: .github/decisions.md
Maintained by: Tendril Project Team