tendril/docs/GITEA/LLM-Gitea-Guidelines.md

LLM Guidelines for Working with Gitea

Purpose: Specific guidelines for AI assistants (LLMs) when working with Gitea-based projects like Tendril.

Last Updated: 2025-01-27

---

Core Principles

1. Always refer to "Gitea" (not "GitHub") when the platform is Gitea
2. Note compatibility when discussing Gitea Actions (compatible with GitHub Actions)
3. Use Gitea terminology consistently
4. Link to Gitea documentation when referencing features

---

Terminology Guidelines

Correct Usage

✅ Use These Terms:

• "Gitea" - The platform
• "Gitea Actions" - CI/CD system
• "Gitea Runners" - CI/CD execution environment
• "Gitea instance" - Self-hosted Gitea server
• "Pull Request" or "PR" - Code review (same as GitHub)
• "Issues" - Bug/feature tracking (same as GitHub)
• "Repository" or "Repo" - Code storage (same as GitHub)

❌ Avoid These Terms (when referring to Gitea):

• "GitHub" - Wrong platform
• "GitHub Actions" - Should be "Gitea Actions" (but note compatibility)
• "GitHub Runners" - Should be "Gitea Runners"
• "GitHub repository" - Should be "Gitea repository"

Compatibility Notes

When discussing workflows or Actions:

• ✅ "Gitea Actions workflows (compatible with GitHub Actions format)"
• ✅ "Gitea Actions uses the same YAML format as GitHub Actions"
• ✅ "Workflows use .github/workflows/ directory (same as GitHub)"

---

Documentation Standards

When Creating Documentation

1. Platform Reference:

   This repository uses **Gitea** for version control and collaboration.
   

2. Actions Reference:

   This project uses **Gitea Actions** for CI/CD. Gitea Actions is compatible 
   with GitHub Actions, so workflows use the same YAML format and 
   `.github/workflows/` directory structure.
   

3. Repository Links:

   Repository: https://git.parkingmeter.info/Mycelium/tendril
   

When Creating Workflow Files

1. File Location: .github/workflows/ (same as GitHub)
2. YAML Format: Identical to GitHub Actions
3. Documentation: Reference as "Gitea Actions workflows"
4. Comments: Note compatibility if relevant

Example:

# Gitea Actions workflow
# Compatible with GitHub Actions format
name: KB Lint

on:
  push:
    paths:
      - 'kb/**/*.md'

When Updating Cursor Rules

1. Use "Gitea Actions" in rules:

   #### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified:
   

2. Note compatibility:

   **Note**: Gitea Actions is compatible with GitHub Actions, so workflows 
   use the same YAML format and `.github/` directory structure.
   

---

Common Scenarios

Scenario 1: Creating a New Workflow

What to do:

1. Create workflow in .github/workflows/
2. Use standard GitHub Actions YAML format
3. Document as "Gitea Actions workflow"
4. Note compatibility in documentation
5. Update .github/CHANGELOG.md
6. Update .github/README.md

Example documentation:

### KB Lint Workflow

**File**: `.github/workflows/kb-lint.yml`

**Purpose**: Validates KB file naming and frontmatter

**Platform**: Gitea Actions (compatible with GitHub Actions format)

**Triggers**: Runs on push and pull requests when KB files change

Scenario 2: Referencing Repository

What to do:

1. Use Gitea repository URL
2. Reference as "Gitea repository"
3. Link to Gitea instance

Example:

**Repository**: https://git.parkingmeter.info/Mycelium/tendril  
**Platform**: Gitea (self-hosted)

Scenario 3: Discussing Features

What to do:

1. Reference Gitea features
2. Note similarities to GitHub when helpful
3. Link to Gitea documentation

Example:

Gitea supports Pull Requests (similar to GitHub) and also provides 
an AGit workflow alternative. For more information, see the 
[Gitea documentation](https://docs.gitea.com/).

---

File Structure Guidelines

Workflow Files

• Location: .github/workflows/
• Format: YAML (same as GitHub Actions)
• Naming: kebab-case.yml
• Documentation: Reference as "Gitea Actions workflows"

Documentation Files

• Location: .github/ or project root
• Content: Use "Gitea" terminology
• Links: Link to Gitea documentation when relevant

Cursor Rules

• Location: .cursorrules or .cursor/rules/
• Content: Use "Gitea Actions" (not "GitHub Actions")
• Notes: Include compatibility notes where relevant

---

Checklist for LLMs

When working with Gitea-based projects:

• Use "Gitea" (not "GitHub") when referring to the platform
• Use "Gitea Actions" (not "GitHub Actions") but note compatibility
• Reference Gitea repository URLs correctly
• Link to Gitea documentation: https://docs.gitea.com/
• Note compatibility when discussing workflows
• Use .github/workflows/ directory (same as GitHub)
• Use standard GitHub Actions YAML format for workflows
• Update .github/CHANGELOG.md when modifying workflows
• Update .github/README.md when adding workflows
• Use Gitea terminology consistently

---

Quick Reference

Repository Information

• Platform: Gitea (self-hosted)
• Instance: git.parkingmeter.info
• Repository: https://git.parkingmeter.info/Mycelium/tendril

Documentation Links

• Gitea Docs: https://docs.gitea.com/
• Gitea Actions: https://docs.gitea.com/usage/actions/
• Gitea API: https://docs.gitea.com/api/

Key Points

1. Gitea is self-hosted (not GitHub)
2. Gitea Actions is compatible with GitHub Actions
3. Workflows use same format and directory structure
4. Terminology should reference "Gitea" consistently

---

Location: docs/GITEA/LLM-Gitea-Guidelines.md
Related: docs/AGENT-GUIDELINES.md, .cursorrules