Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db003786f99787fb7f1591e5af8539efa399b059
tendril/docs/GITEA/Gitea-Basics.md
Data Warrior 0a131a296e feat(phase-0): establish comprehensive documentation and automation system 
Phase 0: Foundation & Cursor Rules Setup - Complete

This commit establishes the foundation for a comprehensive documentation and
project management system for Tendril, following best practices from the
COMPLETE-SYSTEM-REPLICATION-GUIDE.md.

## What Was Created

### 1. Cursor Rules System (.cursorrules)
- Comprehensive rules for AI agent behavior in Cursor IDE
- Phase documentation synchronization rules (auto-update changelog, tasks, decisions)
- KB (Knowledge Base) ingestion and routing rules
- Gitea Actions workflow maintenance rules
- README maintenance rules
- File deletion protection rules
- Customized for Tendril project with Gitea platform

### 2. Directory Structure
- tendril/phases/ - Phase-based project management structure
- kb/ - Knowledge Base system with 8 categories:
  * 01_projects/tendril/ - Project-specific notes
  * 02_systems/ - Infrastructure/tooling
  * 03_research/ - Informal research
  * 04_design/ - Product specs/UX
  * 05_decisions/ - Project-level ADRs
  * 06_glossary/ - Terms/acronyms
  * 07_playbooks/ - How-to guides
  * 08_archive/ - Superseded content
  * Special directories: _guides/, _templates/, _inbox/, _review_queue/, scripts/
- .github/workflows/ - Gitea Actions workflows (compatible with GitHub Actions)
- docs/PROMPTS/ - LLM usage guides

### 3. Agent Guidelines (docs/AGENT-GUIDELINES.md)
- Comprehensive guide for AI agents working on Tendril
- Documents project structure, workflows, and conventions
- Mandatory workflows and critical rules
- Project-specific context (Rust/WASM, Zed extension)
- Links to all documentation systems

### 4. Gitea Documentation (docs/GITEA/)
Complete documentation suite for working with Gitea:
- README.md - Overview and quick reference
- Gitea-Basics.md - Core concepts, features, differences from GitHub
- Gitea-Actions-Guide.md - CI/CD guide with compatibility notes
- Gitea-Workflows.md - Common workflows and best practices
- Gitea-API-Reference.md - API differences and usage
- LLM-Gitea-Guidelines.md - LLM-specific guidelines and terminology

### 5. Phase Updates Documentation (docs/PHASE-UPDATES/)
- COMPLETE-SYSTEM-REPLICATION-GUIDE.md - Complete replication guide
- PHASE-0-GITEA-UPDATES.md - Documents Gitea-specific updates
- README.md - Directory overview and navigation

## Why This Was Done

1. **Establish AI-Friendly Documentation System**
   - Enables consistent AI agent behavior across the project
   - Provides clear guidelines for documentation maintenance
   - Ensures automated synchronization of related documents

2. **Platform-Specific Adaptation (Gitea)**
   - Tendril uses self-hosted Gitea, not GitHub
   - Gitea Actions is compatible with GitHub Actions but needs proper documentation
   - Ensures all references use correct terminology (Gitea vs GitHub)

3. **Foundation for Phase-Based Management**
   - Sets up structure for phase documentation system
   - Prepares for KB system implementation
   - Establishes automation workflows foundation

4. **Knowledge Management**
   - KB system structure ready for capturing project knowledge
   - Templates and guides prepared for future use
   - Index generation system prepared

## How It Benefits the Project

### 1. Automated Documentation Synchronization
- When phase blueprints are modified, related documents (changelog, tasks, decisions)
  are automatically checked and updated
- Reduces manual synchronization errors
- Ensures consistency across all phase documents

### 2. AI Agent Consistency
- Cursor rules ensure all AI interactions follow the same patterns
- Clear guidelines prevent inconsistent documentation
- Automated checks ensure nothing is missed

### 3. Gitea Platform Understanding
- Comprehensive Gitea documentation helps LLMs understand the platform
- Correct terminology prevents confusion (Gitea vs GitHub)
- Workflow compatibility clearly documented

### 4. Scalable Structure
- Phase-based system supports long-term project management
- KB system ready for knowledge capture and organization
- Automation workflows prepared for CI/CD

### 5. Developer Experience
- Clear documentation structure makes onboarding easier
- Automated workflows reduce manual maintenance
- Consistent patterns across all documentation

### 6. Future-Proof Foundation
- Structure supports future phases (1-6)
- KB system ready for knowledge capture
- Automation system ready for workflow implementation

## Technical Details

### Gitea Actions Compatibility
- Gitea Actions uses same YAML format as GitHub Actions
- Same .github/workflows/ directory structure
- Workflows are largely interchangeable
- Documentation notes compatibility throughout

### File Organization
- All documentation organized in docs/ directory
- Phase updates tracked in docs/PHASE-UPDATES/
- Gitea-specific docs in docs/GITEA/
- Agent guidelines in docs/AGENT-GUIDELINES.md

### Cursor Rules Customization
- Project name: Tendril
- Phase directory: tendril/phases/
- KB project: tendril
- Platform: Gitea (self-hosted)

## Next Steps

Phase 0 is complete. Ready for:
- Phase 1: Phase Documentation System setup
- Phase 2: KB System implementation
- Phase 3: Gitea Actions workflows
- Phase 4: LLM Usage Guides
- Phase 5: Documentation migration
- Phase 6: Validation and testing

## Files Added

- .cursorrules (root)
- docs/AGENT-GUIDELINES.md
- docs/GITEA/ (6 files)
- docs/PHASE-UPDATES/ (3 files)
- Directory structures for phases, KB, workflows, and prompts

All files validated with no linter errors.
2025-11-11 11:09:36 -07:00

5.2 KiB
Raw Blame History

Gitea Basics for LLMs

Purpose: Core concepts and features of Gitea that LLMs should understand when working with Gitea-based projects.

Reference: Gitea Official Documentation

What is Gitea?

Gitea is a painless, self-hosted, all-in-one software development service. It includes:

  • Git hosting and repository management
  • Code review (Pull Requests and AGit workflow)
  • Issue tracking and project management
  • CI/CD via Gitea Actions (compatible with GitHub Actions)
  • Package registry (20+ package types: Cargo, npm, PyPI, Maven, etc.)
  • Team collaboration tools

Key Point: Gitea is similar to GitHub, Bitbucket, and GitLab, but is designed to be lightweight and self-hosted.

Core Features

1. Code Hosting

  • Create and manage repositories
  • Browse commit history and code files
  • Review and merge code submissions
  • Manage collaborators
  • Handle branches, tags, cherry-picking, hooks
  • Integrated collaboration tools

2. Code Review

  • Pull Request workflow (same as GitHub)
  • AGit workflow (Gitea-specific alternative)
  • Online code browsing
  • Review comments and feedback
  • Inline code modifications

3. Issue Tracking

  • Track requirements, features, and bugs
  • Support for branches, tags, milestones
  • Assignments, time tracking, due dates
  • Dependencies between issues
  • Project columns and boards

4. CI/CD (Gitea Actions)

  • Compatible with GitHub Actions
  • Write workflows in YAML format
  • Reuse existing Actions plugins
  • Actions plugins can be downloaded from any Git website
  • Same .github/workflows/ directory structure

5. Package Registry

Supports 20+ package types:

  • Cargo, Chef, Composer, Conan, Conda
  • Container, Helm, Maven, npm, NuGet
  • Pub, PyPI, RubyGems, Vagrant
  • And more

6. Security

  • User permission management
  • Access control lists (ACLs)
  • Security-focused design
  • Non-root system account recommended

System Requirements

  • Minimum: Raspberry Pi 3 (for small workloads)
  • Typical: 2 CPU cores, 1GB RAM (for small teams/projects)
  • Git: Version 2.0.0 or later required
  • Platforms: Linux, macOS, Windows (x86, amd64, ARM, PowerPC)

Key Differences from GitHub

1. Self-Hosted

  • Runs on your own infrastructure
  • Full control over data and access
  • No dependency on external services
  • Can be air-gapped if needed

2. Lightweight

  • Designed to be fast and resource-efficient
  • Suitable for resource-limited environments
  • Lower system requirements than GitHub/GitLab

3. Open Source

  • MIT licensed
  • Community-driven development
  • Transparent codebase
  • No vendor lock-in

4. Actions Compatibility

  • Gitea Actions uses same format as GitHub Actions
  • Workflows are largely interchangeable
  • Some GitHub-specific features may not be available
  • Actions can be sourced from any Git repository

5. API Differences

  • Gitea API is similar to GitHub's but not identical
  • Some endpoints may differ
  • Authentication methods are similar
  • Webhook formats are compatible

Terminology

Same as GitHub

  • Repository / Repo - Code storage
  • Branch - Code versioning
  • Pull Request / PR - Code review request
  • Issue - Bug/feature tracking
  • Commit - Code change
  • Tag - Release marker
  • Fork - Copy of repository
  • Clone - Local copy

Gitea-Specific

  • AGit workflow - Alternative to Pull Request workflow
  • Gitea Actions - CI/CD system (compatible with GitHub Actions)
  • Self-hosted - Running on your own infrastructure

Common Workflows

Creating a Repository

  1. Log in to Gitea instance
  2. Click "New Repository"
  3. Configure repository settings
  4. Push code or initialize with README

Creating a Pull Request

  1. Create a branch
  2. Make changes and commit
  3. Push branch to Gitea
  4. Click "New Pull Request"
  5. Review and merge (same as GitHub)

Using Gitea Actions

  1. Create .github/workflows/ directory
  2. Write workflow YAML (same format as GitHub Actions)
  3. Push to repository
  4. Gitea Actions will execute workflows

Managing Issues

  1. Create issue from repository
  2. Assign to team members
  3. Link to milestones, labels, projects
  4. Track dependencies and due dates

For LLMs: Important Notes

When Documenting

  • Always refer to "Gitea" (not "GitHub") when the platform is Gitea
  • Note that Gitea Actions is compatible with GitHub Actions
  • Use Gitea terminology consistently
  • Link to Gitea documentation: https://docs.gitea.com/

When Creating Workflows

  • Use .github/workflows/ directory (same as GitHub)
  • YAML format is identical to GitHub Actions
  • Reference as "Gitea Actions workflows"
  • Note compatibility in documentation

When Working with API

  • Gitea API is similar but not identical to GitHub's
  • Check Gitea API documentation for specific endpoints
  • Authentication uses tokens (similar to GitHub)
  • Webhooks are compatible

References

Location: docs/GITEA/Gitea-Basics.md
Last Updated: 2025-01-27

Reference in New Issue View Git Blame Copy Permalink