chore: update KB index [skip ci]
This commit is contained in:
Gitea Actions
240
.github/LLM-Usage-Guide--tendril.md
vendored
Normal file
240
.github/LLM-Usage-Guide--tendril.md
vendored
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user