112 lines
3.5 KiB
Markdown
112 lines
3.5 KiB
Markdown
# 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
|
|
|