Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6a4683022f84229e666c36bd349afb0223ee8058
tendril/.github/LLM-Usage-Guide--tendril.md
Gitea Actions 830629f105 chore: update KB index [skip ci]
2025-11-11 11:53:12 -07:00

7.0 KiB
Raw Blame History

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:

## [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:

### [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 View Git Blame Copy Permalink