241 lines
7.0 KiB
Markdown
241 lines
7.0 KiB
Markdown
# LLM Usage Guide for Gitea Actions Workflows — tendril
|
|
|
|
_Last updated: 2025-01-27_
|
|
|
|
## Purpose
|
|
|
|
This guide provides instructions for AI assistants (LLMs) on how to work with Gitea Actions workflows, automation, and the `.github/` directory structure in this repository.
|
|
|
|
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure.
|
|
|
|
---
|
|
|
|
## Repository Context
|
|
|
|
**Repository**: tendril
|
|
**Repository URL**: https://git.parkingmeter.info/Mycelium/tendril
|
|
**Platform**: Gitea (self-hosted)
|
|
**Primary System**: Tendril - Zed IDE extension for Gitea integration
|
|
**Automation Focus**: KB system validation and index maintenance
|
|
|
|
---
|
|
|
|
## Understanding .github Directory Structure
|
|
|
|
### Workflows (`workflows/`)
|
|
|
|
Gitea Actions workflows automate repository operations:
|
|
|
|
- **`kb-lint.yml`** - Validates KB file naming, frontmatter, and structure
|
|
- **`kb-index-update.yml`** - Auto-updates KB index on push to main when KB files change
|
|
|
|
### Documentation
|
|
|
|
- **`README.md`** - Overview of .github directory and workflows
|
|
- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder
|
|
- **`decisions.md`** - Documents decisions about workflows and automation
|
|
- **`LLM-Usage-Guide--tendril.md`** (this file) - LLM instructions for this repo
|
|
|
|
---
|
|
|
|
## Working with Workflows
|
|
|
|
### When Modifying Workflows
|
|
|
|
**MANDATORY**: When any workflow file is modified:
|
|
|
|
1. **Update `.github/CHANGELOG.md`**:
|
|
- Add entry with date and description
|
|
- Document what changed and why
|
|
- Include affected workflow name
|
|
|
|
2. **Update `.github/decisions.md`** (if decision-related):
|
|
- Document the decision behind the change
|
|
- Explain rationale and alternatives considered
|
|
- Note impact on automation
|
|
|
|
3. **Update `.github/README.md`** (if structure changes):
|
|
- Update workflow descriptions if behavior changed
|
|
- Add new workflows to overview
|
|
- Remove references to deleted workflows
|
|
|
|
4. **Test the workflow**:
|
|
- Use `workflow_dispatch` trigger if available
|
|
- Verify expected behavior
|
|
- Check for errors in Gitea Actions tab
|
|
|
|
5. **Consult Gitea documentation**:
|
|
- Reference `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance
|
|
- Note any Gitea-specific differences from GitHub Actions
|
|
|
|
### When Adding New Workflows
|
|
|
|
1. Create workflow file in `.github/workflows/`
|
|
2. Update `.github/CHANGELOG.md` - Document new workflow
|
|
3. Update `.github/decisions.md` - Document why workflow was added
|
|
4. Update `.github/README.md` - Add to workflow overview
|
|
5. Test workflow - Verify it runs successfully
|
|
6. Update this guide - Add instructions if needed
|
|
|
|
### When Removing Workflows
|
|
|
|
1. Update `.github/CHANGELOG.md` - Document removal and reason
|
|
2. Update `.github/decisions.md` - Document why workflow was removed
|
|
3. Update `.github/README.md` - Remove from overview
|
|
4. Update this guide - Remove references
|
|
|
|
---
|
|
|
|
## Workflow-Specific Instructions
|
|
|
|
### KB Lint Workflow
|
|
|
|
**File**: `.github/workflows/kb-lint.yml`
|
|
|
|
**Purpose**: Validates KB file naming, frontmatter, and structure on push and pull requests
|
|
|
|
**When to modify**:
|
|
- KB validation rules change
|
|
- KB file naming pattern changes
|
|
- Frontmatter requirements change
|
|
- New validation rules needed
|
|
|
|
**Validation Rules**:
|
|
- Filename pattern: `YYYY-MM-DD--slug--type.md`
|
|
- Frontmatter must exist and be valid YAML
|
|
- All 18 required fields must be present
|
|
- Date in frontmatter must match filename date
|
|
- Type in frontmatter must match filename type
|
|
- `routing_confidence` must be numeric 0.00-1.00
|
|
- Files with `routing_confidence < 0.60` must be in `_review_queue/`
|
|
|
|
**Exclusions**:
|
|
- `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md` are excluded from validation
|
|
|
|
**Validation**:
|
|
- Workflow runs on push and pull requests when `kb/**/*.md` files change
|
|
- Provides clear error messages for each validation failure
|
|
- Exits with error code if any validation fails
|
|
|
|
---
|
|
|
|
### KB Index Update Workflow
|
|
|
|
**File**: `.github/workflows/kb-index-update.yml`
|
|
|
|
**Purpose**: Automatically regenerates `kb/_index.md` when KB files change on main branch
|
|
|
|
**When to modify**:
|
|
- Index generation script changes
|
|
- Index update logic needs modification
|
|
- Commit message format needs change
|
|
- Branch name changes (if not using `main`)
|
|
|
|
**Workflow Steps**:
|
|
1. Checkout repository
|
|
2. Run `kb/scripts/generate-index.sh`
|
|
3. Check if `kb/_index.md` changed
|
|
4. If changed, commit and push update
|
|
5. Use git user: "Gitea Actions" <actions@gitea.io>
|
|
|
|
**Validation**:
|
|
- Workflow runs on push to `main` branch when `kb/**/*.md` files change
|
|
- Excludes `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md`
|
|
- Uses `|| exit 0` to handle case where index hasn't changed
|
|
- Requires `contents: write` permission to push changes
|
|
|
|
---
|
|
|
|
## Documentation Maintenance
|
|
|
|
### .github/CHANGELOG.md
|
|
|
|
**Purpose**: Track all changes to workflows and .github folder
|
|
|
|
**Format**:
|
|
```markdown
|
|
## [YYYY-MM-DD] Brief Description
|
|
|
|
### Added
|
|
- New workflow or feature
|
|
|
|
### Changed
|
|
- Modified workflow behavior
|
|
|
|
### Fixed
|
|
- Bug fix or correction
|
|
```
|
|
|
|
**When to update**: Every time a workflow file is modified
|
|
|
|
### .github/decisions.md
|
|
|
|
**Purpose**: Document decisions about workflows and automation
|
|
|
|
**Format**:
|
|
```markdown
|
|
### [YYYY-MM-DD] Decision Title
|
|
|
|
**Context**: What prompted this decision
|
|
**Decision**: What was decided
|
|
**Rationale**: Why this approach
|
|
**Alternatives**: Other options considered
|
|
**Impact**: What this affects
|
|
```
|
|
|
|
**When to update**: When making significant workflow decisions
|
|
|
|
---
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Workflow
|
|
|
|
1. Create workflow file in `.github/workflows/`
|
|
2. Add workflow to `.github/README.md` overview
|
|
3. Document in `.github/CHANGELOG.md`
|
|
4. Document decision in `.github/decisions.md` (if applicable)
|
|
5. Test workflow with `workflow_dispatch` (if available)
|
|
6. Commit all changes together
|
|
|
|
### Modifying an Existing Workflow
|
|
|
|
1. Make workflow changes
|
|
2. Update `.github/CHANGELOG.md` with change description
|
|
3. Update `.github/decisions.md` if decision-related
|
|
4. Update `.github/README.md` if behavior changed significantly
|
|
5. Test workflow
|
|
6. Commit changes
|
|
|
|
---
|
|
|
|
## Validation Checklist
|
|
|
|
Before committing workflow changes:
|
|
|
|
- [ ] Workflow file syntax is valid YAML
|
|
- [ ] Workflow tested with `workflow_dispatch` (if available)
|
|
- [ ] `.github/CHANGELOG.md` updated with change description
|
|
- [ ] `.github/decisions.md` updated (if decision-related)
|
|
- [ ] `.github/README.md` updated (if structure/behavior changed)
|
|
- [ ] All changes committed together
|
|
- [ ] Commit message follows conventional format: `ci(workflows): description`
|
|
- [ ] Consulted `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance
|
|
|
|
---
|
|
|
|
## Gitea-Specific Notes
|
|
|
|
- **Platform**: Gitea (self-hosted)
|
|
- **Actions**: Gitea Actions (compatible with GitHub Actions format)
|
|
- **Runners**: Must be configured on Gitea instance
|
|
- **Documentation**: See `docs/GITEA/Gitea-Actions-Guide.md` for detailed guidance
|
|
- **API**: See `docs/GITEA/Gitea-API-Reference.md` for API differences
|
|
|
|
---
|
|
|
|
**Repository**: `tendril`
|
|
**Location**: `.github/LLM-Usage-Guide--tendril.md`
|
|
**Maintained by**: Tendril Project Team
|
|
|