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.
This commit is contained in:
213
docs/GITEA/Gitea-Basics.md
Normal file
213
docs/GITEA/Gitea-Basics.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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](https://docs.gitea.com/)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
- **Gitea Documentation**: https://docs.gitea.com/
|
||||
- **Gitea Features**: https://docs.gitea.com/installation/comparison#general-features
|
||||
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
|
||||
- **Gitea API**: https://docs.gitea.com/api/
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/GITEA/Gitea-Basics.md`
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
Reference in New Issue
Block a user