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:
217
docs/AGENT-GUIDELINES.md
Normal file
217
docs/AGENT-GUIDELINES.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# Agent Guidelines for Tendril
|
||||
|
||||
**Purpose**: This document provides guidelines for AI agents (like Cursor AI) working on the Tendril project. It defines the project structure, documentation standards, and workflow expectations.
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Tendril** is a Zed IDE extension that integrates with Gitea through the Model Context Protocol (MCP). It provides seamless access to Gitea repositories, issues, pull requests, and more directly within the Zed editor.
|
||||
|
||||
**Repository**: https://git.parkingmeter.info/Mycelium/tendril
|
||||
**Current Version**: v0.1.0
|
||||
**Language**: Rust (compiled to WASM for Zed extension)
|
||||
**License**: Apache 2.0
|
||||
|
||||
---
|
||||
|
||||
## Documentation System Architecture
|
||||
|
||||
Tendril uses a comprehensive documentation system with the following components:
|
||||
|
||||
### Phase Documentation System
|
||||
|
||||
**Location**: `tendril/phases/phase-XX-name/`
|
||||
|
||||
Each phase has four synchronized documents:
|
||||
- **`blueprint.md`** - Complete phase specification
|
||||
- **`tasks.md`** - Task tracking (mirrors Gitea issues)
|
||||
- **`decisions.md`** - Architecture Decision Records (ADRs)
|
||||
- **`changelog.md`** - Change history
|
||||
|
||||
**Critical Rule**: When `blueprint.md` is modified, ALL related documents must be checked and updated in the same session.
|
||||
|
||||
### Knowledge Base (KB) System
|
||||
|
||||
**Location**: `kb/`
|
||||
|
||||
The KB system provides a lightweight, LLM-friendly staging area for external information:
|
||||
- `kb/01_projects/tendril/` - Project-specific notes
|
||||
- `kb/02_systems/` - Infrastructure/tooling
|
||||
- `kb/03_research/` - Informal research
|
||||
- `kb/04_design/` - Product specs/UX
|
||||
- `kb/05_decisions/` - Project-level ADRs
|
||||
- `kb/06_glossary/` - Terms/acronyms
|
||||
- `kb/07_playbooks/` - How-to guides
|
||||
- `kb/08_archive/` - Superseded content
|
||||
|
||||
**KB File Naming**: `YYYY-MM-DD--slug--type.md`
|
||||
**KB Frontmatter**: All KB files require complete YAML frontmatter with 18 required fields.
|
||||
|
||||
### Gitea Automation
|
||||
|
||||
**Location**: `.github/`
|
||||
|
||||
- `.github/workflows/` - Gitea Actions workflows (compatible with GitHub Actions format)
|
||||
- `.github/README.md` - Automation overview
|
||||
- `.github/CHANGELOG.md` - Workflow change tracking
|
||||
- `.github/decisions.md` - Automation decisions
|
||||
|
||||
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Documentation is the Single Source of Truth** - Always read phase blueprints before making changes
|
||||
2. **Synchronization is Mandatory** - Related documents must stay in sync automatically
|
||||
3. **LLM-Friendly Structure** - All documentation is structured for AI agent consumption
|
||||
4. **Incremental Updates** - Update documentation as you work, not at the end
|
||||
5. **Validation at Every Step** - Automated validation ensures consistency
|
||||
|
||||
---
|
||||
|
||||
## Mandatory Workflows
|
||||
|
||||
### When Editing Phase Blueprints
|
||||
|
||||
1. **Read related documents first**:
|
||||
- `changelog.md` - Check recent changes
|
||||
- `tasks.md` - Understand current task status
|
||||
- `decisions.md` - Review existing ADRs
|
||||
|
||||
2. **After editing `blueprint.md`**:
|
||||
- Update `changelog.md` with today's date and description
|
||||
- Sync `tasks.md` with blueprint deliverables and definition of done
|
||||
- Review `decisions.md` for new ADRs needed
|
||||
- Verify project name consistency across all documents
|
||||
|
||||
3. **Before completing**:
|
||||
- Provide summary of all files modified
|
||||
- Ask user if they want to push changes
|
||||
|
||||
### When Creating KB Files
|
||||
|
||||
1. **Before creating**:
|
||||
- Check `kb/_index.md` for existing related content
|
||||
- Determine appropriate category using routing decision tree
|
||||
- Assess routing confidence (0.00-1.00)
|
||||
|
||||
2. **After creating**:
|
||||
- Run `kb/scripts/generate-index.sh` to update index
|
||||
- Update `kb/CHANGELOG.md` with entry
|
||||
- Commit all three changes together
|
||||
|
||||
### When Modifying Gitea Actions Workflows
|
||||
|
||||
1. **Update `.github/CHANGELOG.md`** - Document what changed
|
||||
2. **Update `.github/decisions.md`** - Document decision rationale (if applicable)
|
||||
3. **Update `.github/README.md`** - Update workflow descriptions (if needed)
|
||||
|
||||
**Note**: Gitea Actions workflows use the same YAML format as GitHub Actions, so existing GitHub Actions workflows can be used with minimal or no modifications.
|
||||
|
||||
### When Completing Work Sessions
|
||||
|
||||
1. **Check README.md**:
|
||||
- Verify phase statuses are accurate
|
||||
- Update if phase statuses changed
|
||||
- Verify links are correct
|
||||
|
||||
2. **Verify consistency**:
|
||||
- Project name matches across documents
|
||||
- Dates are consistent
|
||||
- Status indicators are aligned
|
||||
|
||||
---
|
||||
|
||||
## File Structure Conventions
|
||||
|
||||
### Directory Naming
|
||||
- **Phase directories**: `phase-XX-name` where XX is zero-padded (00, 01, 02, etc.)
|
||||
- **KB categories**: `01_projects/`, `02_systems/`, etc. (numbered for ordering)
|
||||
- **Special KB directories**: `_guides/`, `_templates/`, `_inbox/`, `_review_queue/` (underscore prefix)
|
||||
|
||||
### File Naming
|
||||
- **Phase documentation**: `blueprint.md`, `tasks.md`, `decisions.md`, `changelog.md`
|
||||
- **KB files**: `YYYY-MM-DD--slug--type.md`
|
||||
- **Workflows**: `kebab-case.yml`
|
||||
|
||||
### Commit Messages
|
||||
|
||||
**Format**: `type(scope): description`
|
||||
|
||||
**Types**:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `chore`: Maintenance tasks
|
||||
- `ci`: CI/CD changes
|
||||
|
||||
**Examples**:
|
||||
- `feat(phase-01): Add Zapier integration`
|
||||
- `fix(phase-02): Resolve web link capture (#123)`
|
||||
- `docs(kb): add api-auth-decision and update index/changelog`
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### NEVER Do These Things
|
||||
|
||||
- ❌ **NEVER delete files or folders when committing or pushing**
|
||||
- ❌ NEVER edit blueprint.md without checking related documents
|
||||
- ❌ NEVER leave related documents out of sync
|
||||
- ❌ NEVER assume related documents are already updated
|
||||
- ❌ NEVER skip KB index/changelog updates
|
||||
- ❌ NEVER complete work without checking README.md
|
||||
|
||||
### ALWAYS Do These Things
|
||||
|
||||
- ✅ ALWAYS read related documents before making changes
|
||||
- ✅ ALWAYS update related documents in the same session
|
||||
- ✅ ALWAYS verify consistency across all phase documents
|
||||
- ✅ ALWAYS run KB index generation after KB file changes
|
||||
- ✅ ALWAYS check README.md after significant changes
|
||||
- ✅ ALWAYS provide summaries of what was updated
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Context
|
||||
|
||||
### Technology Stack
|
||||
- **Language**: Rust
|
||||
- **Target**: WASM (WebAssembly) for Zed extension
|
||||
- **Dependencies**: zed_extension_api, serde, schemars
|
||||
- **Build**: `cargo build --target wasm32-unknown-unknown --release`
|
||||
|
||||
### Key Files
|
||||
- `src/mcp_server_gitea.rs` - Main extension logic
|
||||
- `extension.toml` - Zed extension manifest
|
||||
- `Cargo.toml` - Rust project configuration
|
||||
- `configuration/default_settings.jsonc` - Configuration template
|
||||
|
||||
### Current Status
|
||||
- **Version**: v0.1.0
|
||||
- **Status**: Feature-complete for core functionality
|
||||
- **Features**: Binary path resolution, Docker support, cross-platform detection
|
||||
- **Limitations**: SSE mode not supported (Zed API limitation)
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're unsure about:
|
||||
- **Documentation structure**: See `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
|
||||
- **KB system**: See `kb/README.md` and `kb/_guides/`
|
||||
- **Phase documentation**: See `tendril/phases/phase-00-foundation/` for examples
|
||||
- **Gitea automation**: See `.github/README.md` and `.github/LLM-Usage-Guide--tendril.md`
|
||||
- **Gitea platform**: See `docs/GITEA/` for comprehensive Gitea documentation
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/AGENT-GUIDELINES.md`
|
||||
**Maintained by**: Tendril Project Maintainers
|
||||
**Based on**: `docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
|
||||
|
||||
243
docs/GITEA/Gitea-API-Reference.md
Normal file
243
docs/GITEA/Gitea-API-Reference.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Gitea API Reference for LLMs
|
||||
|
||||
**Purpose**: API differences and considerations when working with Gitea programmatically.
|
||||
|
||||
**Reference**: [Gitea API Documentation](https://docs.gitea.com/api/)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Gitea provides a REST API that is **similar to GitHub's API** but not identical. The API allows programmatic access to repositories, issues, pull requests, and more.
|
||||
|
||||
**Base URL**: `https://your-gitea-instance.com/api/v1`
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### Personal Access Token
|
||||
|
||||
**Creating a token**:
|
||||
1. Log in to Gitea
|
||||
2. Go to Settings → Applications → Generate New Token
|
||||
3. Set name and permissions
|
||||
4. Copy token
|
||||
|
||||
**Using token**:
|
||||
```bash
|
||||
curl -H "Authorization: token YOUR_TOKEN" \
|
||||
https://git.parkingmeter.info/api/v1/user
|
||||
```
|
||||
|
||||
**In code**:
|
||||
```rust
|
||||
let client = reqwest::Client::new();
|
||||
let response = client
|
||||
.get("https://git.parkingmeter.info/api/v1/user")
|
||||
.header("Authorization", format!("token {}", token))
|
||||
.send()
|
||||
.await?;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Endpoints
|
||||
|
||||
### User Information
|
||||
|
||||
**Get authenticated user**:
|
||||
```
|
||||
GET /api/v1/user
|
||||
```
|
||||
|
||||
**Get user by username**:
|
||||
```
|
||||
GET /api/v1/users/{username}
|
||||
```
|
||||
|
||||
### Repositories
|
||||
|
||||
**List repositories**:
|
||||
```
|
||||
GET /api/v1/user/repos
|
||||
GET /api/v1/users/{username}/repos
|
||||
GET /api/v1/orgs/{org}/repos
|
||||
```
|
||||
|
||||
**Get repository**:
|
||||
```
|
||||
GET /api/v1/repos/{owner}/{repo}
|
||||
```
|
||||
|
||||
**Create repository**:
|
||||
```
|
||||
POST /api/v1/user/repos
|
||||
```
|
||||
|
||||
### Issues
|
||||
|
||||
**List issues**:
|
||||
```
|
||||
GET /api/v1/repos/{owner}/{repo}/issues
|
||||
```
|
||||
|
||||
**Get issue**:
|
||||
```
|
||||
GET /api/v1/repos/{owner}/{repo}/issues/{index}
|
||||
```
|
||||
|
||||
**Create issue**:
|
||||
```
|
||||
POST /api/v1/repos/{owner}/{repo}/issues
|
||||
```
|
||||
|
||||
### Pull Requests
|
||||
|
||||
**List pull requests**:
|
||||
```
|
||||
GET /api/v1/repos/{owner}/{repo}/pulls
|
||||
```
|
||||
|
||||
**Get pull request**:
|
||||
```
|
||||
GET /api/v1/repos/{owner}/{repo}/pulls/{index}
|
||||
```
|
||||
|
||||
**Create pull request**:
|
||||
```
|
||||
POST /api/v1/repos/{owner}/{repo}/pulls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Differences from GitHub API
|
||||
|
||||
### 1. Base URL
|
||||
|
||||
- **GitHub**: `https://api.github.com`
|
||||
- **Gitea**: `https://your-instance.com/api/v1`
|
||||
|
||||
### 2. Issue/PR Numbers
|
||||
|
||||
- **GitHub**: Uses sequential numbers across repository
|
||||
- **Gitea**: Uses index (similar, but may differ in some cases)
|
||||
|
||||
### 3. Some Endpoints
|
||||
|
||||
- Gitea may have different endpoints for some operations
|
||||
- Check Gitea API documentation for specific endpoints
|
||||
- Most common operations are similar
|
||||
|
||||
### 4. Webhooks
|
||||
|
||||
- Gitea webhooks are compatible with GitHub format
|
||||
- Same payload structure
|
||||
- Same event types (push, pull_request, etc.)
|
||||
|
||||
---
|
||||
|
||||
## For LLMs: API Usage Guidelines
|
||||
|
||||
### When Documenting API Usage
|
||||
|
||||
**Reference Gitea API**:
|
||||
```markdown
|
||||
## API Integration
|
||||
|
||||
This project uses the **Gitea API** for programmatic access.
|
||||
|
||||
**Base URL**: `https://git.parkingmeter.info/api/v1`
|
||||
|
||||
**Authentication**: Personal Access Token
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
curl -H "Authorization: token YOUR_TOKEN" \
|
||||
https://git.parkingmeter.info/api/v1/user/repos
|
||||
```
|
||||
```
|
||||
|
||||
### When Creating API Clients
|
||||
|
||||
**Use Gitea base URL**:
|
||||
```rust
|
||||
const GITEA_BASE_URL: &str = "https://git.parkingmeter.info/api/v1";
|
||||
```
|
||||
|
||||
**Use Gitea authentication**:
|
||||
```rust
|
||||
let client = reqwest::Client::new();
|
||||
let response = client
|
||||
.get(&format!("{}/user", GITEA_BASE_URL))
|
||||
.header("Authorization", format!("token {}", token))
|
||||
.send()
|
||||
.await?;
|
||||
```
|
||||
|
||||
### When Referencing Documentation
|
||||
|
||||
**Link to Gitea API docs**:
|
||||
```markdown
|
||||
For complete API documentation, see:
|
||||
https://docs.gitea.com/api/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Listing Repositories
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: token YOUR_TOKEN" \
|
||||
https://git.parkingmeter.info/api/v1/user/repos
|
||||
```
|
||||
|
||||
### 2. Creating an Issue
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Authorization: token YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title":"New Issue","body":"Issue description"}' \
|
||||
https://git.parkingmeter.info/api/v1/repos/owner/repo/issues
|
||||
```
|
||||
|
||||
### 3. Creating a Pull Request
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Authorization: token YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title":"PR Title","head":"feature-branch","base":"main"}' \
|
||||
https://git.parkingmeter.info/api/v1/repos/owner/repo/pulls
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
**Tendril** uses the Gitea MCP server for integration with Zed IDE. The MCP server provides:
|
||||
|
||||
- Repository management
|
||||
- Issue management
|
||||
- Pull request management
|
||||
- File operations
|
||||
- And more
|
||||
|
||||
**Reference**: See `src/mcp_server_gitea.rs` for implementation details.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Gitea API Docs**: https://docs.gitea.com/api/
|
||||
- **API Overview**: https://docs.gitea.com/api/overview/
|
||||
- **Authentication**: https://docs.gitea.com/api/authentication/
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/GITEA/Gitea-API-Reference.md`
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
286
docs/GITEA/Gitea-Actions-Guide.md
Normal file
286
docs/GITEA/Gitea-Actions-Guide.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Gitea Actions Guide for LLMs
|
||||
|
||||
**Purpose**: Guide for LLMs working with Gitea Actions (CI/CD system compatible with GitHub Actions).
|
||||
|
||||
**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Gitea Actions** is Gitea's CI/CD system that is **compatible with GitHub Actions**. This means:
|
||||
|
||||
- Same YAML workflow format
|
||||
- Same `.github/workflows/` directory structure
|
||||
- Same triggers and syntax
|
||||
- Existing GitHub Actions workflows work with minimal or no modifications
|
||||
- Actions plugins can be downloaded from any Git website
|
||||
|
||||
---
|
||||
|
||||
## Key Compatibility Points
|
||||
|
||||
### 1. Directory Structure
|
||||
|
||||
**Same as GitHub**:
|
||||
```
|
||||
.github/
|
||||
└── workflows/
|
||||
├── workflow1.yml
|
||||
├── workflow2.yml
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 2. YAML Format
|
||||
|
||||
**Identical to GitHub Actions**:
|
||||
```yaml
|
||||
name: Workflow Name
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Run command
|
||||
run: echo "Hello, Gitea Actions!"
|
||||
```
|
||||
|
||||
### 3. Triggers
|
||||
|
||||
**Same triggers as GitHub Actions**:
|
||||
- `push` - On push to repository
|
||||
- `pull_request` - On pull request events
|
||||
- `workflow_dispatch` - Manual trigger
|
||||
- `schedule` - Scheduled runs (cron syntax)
|
||||
- `repository_dispatch` - External events
|
||||
|
||||
### 4. Runners
|
||||
|
||||
Gitea Actions uses **Gitea Runners** (similar to GitHub Runners):
|
||||
- Self-hosted runners
|
||||
- Can run on various platforms
|
||||
- Register runners with Gitea instance
|
||||
- Similar to GitHub Actions runners
|
||||
|
||||
---
|
||||
|
||||
## Differences from GitHub Actions
|
||||
|
||||
### 1. Actions Marketplace
|
||||
|
||||
- **GitHub**: Centralized marketplace at github.com/marketplace
|
||||
- **Gitea**: Actions can be downloaded from any Git website
|
||||
- **Impact**: Actions plugins can come from GitHub, Gitea, or any Git repository
|
||||
|
||||
### 2. Runner Registration
|
||||
|
||||
- **GitHub**: Runners managed by GitHub (or self-hosted)
|
||||
- **Gitea**: All runners are self-hosted
|
||||
- **Impact**: Must register and manage your own runners
|
||||
|
||||
### 3. Some GitHub-Specific Features
|
||||
|
||||
- Some GitHub Actions features may not be available
|
||||
- Check Gitea Actions documentation for specific limitations
|
||||
- Most common workflows work identically
|
||||
|
||||
---
|
||||
|
||||
## Creating Workflows
|
||||
|
||||
### Basic Workflow Template
|
||||
|
||||
```yaml
|
||||
name: Workflow Name
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
job-name:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Run command
|
||||
run: |
|
||||
echo "Running in Gitea Actions"
|
||||
# Your commands here
|
||||
```
|
||||
|
||||
### Using Actions from Different Sources
|
||||
|
||||
**From GitHub**:
|
||||
```yaml
|
||||
- uses: actions/checkout@v4
|
||||
```
|
||||
|
||||
**From Gitea**:
|
||||
```yaml
|
||||
- uses: gitea.com/owner/action@v1
|
||||
```
|
||||
|
||||
**From Any Git Repository**:
|
||||
```yaml
|
||||
- uses: https://git.example.com/owner/action@v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For LLMs: Documentation Guidelines
|
||||
|
||||
### When Creating Workflow Documentation
|
||||
|
||||
1. **Reference as "Gitea Actions"**:
|
||||
- "This workflow runs in Gitea Actions"
|
||||
- "Gitea Actions will execute this workflow on push"
|
||||
|
||||
2. **Note Compatibility**:
|
||||
- "Gitea Actions is compatible with GitHub Actions"
|
||||
- "This workflow uses the same YAML format as GitHub Actions"
|
||||
|
||||
3. **Use Correct Terminology**:
|
||||
- "Gitea Actions workflows" (not "GitHub Actions workflows")
|
||||
- "Gitea Runners" (not "GitHub Runners")
|
||||
- But note: "Same format as GitHub Actions"
|
||||
|
||||
### When Creating Workflow Files
|
||||
|
||||
1. **Use `.github/workflows/` directory** (same as GitHub)
|
||||
2. **YAML format is identical** to GitHub Actions
|
||||
3. **Reference in documentation** as "Gitea Actions workflows"
|
||||
4. **Note compatibility** when relevant
|
||||
|
||||
### Example Documentation
|
||||
|
||||
```markdown
|
||||
## CI/CD Workflows
|
||||
|
||||
This repository uses **Gitea Actions** for continuous integration and deployment.
|
||||
|
||||
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/workflows/` directory structure.
|
||||
|
||||
### Workflows
|
||||
|
||||
- **`kb-lint.yml`** - Validates KB file naming and frontmatter
|
||||
- **`kb-index-update.yml`** - Auto-updates KB index on push
|
||||
|
||||
All workflows are located in `.github/workflows/` and use standard GitHub Actions YAML format.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Workflow Patterns
|
||||
|
||||
### Linting Workflow
|
||||
|
||||
```yaml
|
||||
name: Lint
|
||||
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'src/**/*.rs'
|
||||
pull_request:
|
||||
paths:
|
||||
- 'src/**/*.rs'
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Run linter
|
||||
run: cargo clippy
|
||||
```
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
```yaml
|
||||
name: Test
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Run tests
|
||||
run: cargo test
|
||||
```
|
||||
|
||||
### Index Update Workflow
|
||||
|
||||
```yaml
|
||||
name: Update Index
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
paths:
|
||||
- 'kb/**/*.md'
|
||||
|
||||
jobs:
|
||||
update:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Generate index
|
||||
run: ./kb/scripts/generate-index.sh
|
||||
- name: Commit changes
|
||||
run: |
|
||||
git config user.name "Gitea Actions"
|
||||
git config user.email "actions@gitea.io"
|
||||
git add kb/_index.md
|
||||
git commit -m "chore: update KB index" || exit 0
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Workflow Not Running
|
||||
|
||||
1. **Check runner registration**: Ensure runners are registered with Gitea instance
|
||||
2. **Check workflow syntax**: Validate YAML syntax
|
||||
3. **Check triggers**: Verify `on:` conditions match events
|
||||
4. **Check permissions**: Ensure workflow has necessary permissions
|
||||
|
||||
### Actions Not Found
|
||||
|
||||
1. **Check action source**: Verify action URL is correct
|
||||
2. **Check network access**: Ensure runner can access action repository
|
||||
3. **Use full URL**: For custom actions, use full Git URL
|
||||
|
||||
### Runner Issues
|
||||
|
||||
1. **Check runner status**: Verify runner is online and connected
|
||||
2. **Check runner labels**: Ensure `runs-on` matches runner labels
|
||||
3. **Check runner logs**: Review runner logs for errors
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/
|
||||
- **Gitea Runner**: https://docs.gitea.com/usage/actions/runner/
|
||||
- **Workflow Syntax**: https://docs.gitea.com/usage/actions/usage/
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/GITEA/Gitea-Actions-Guide.md`
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
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
|
||||
|
||||
278
docs/GITEA/Gitea-Workflows.md
Normal file
278
docs/GITEA/Gitea-Workflows.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# Gitea Workflows for LLMs
|
||||
|
||||
**Purpose**: Common workflows and best practices for working with Gitea repositories.
|
||||
|
||||
**Reference**: [Gitea Usage Documentation](https://docs.gitea.com/usage/)
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### 1. Repository Setup
|
||||
|
||||
**Creating a new repository**:
|
||||
1. Log in to Gitea instance
|
||||
2. Click "New Repository" or "+" → "New Repository"
|
||||
3. Configure repository settings:
|
||||
- Name, description
|
||||
- Visibility (public/private)
|
||||
- Initialize with README (optional)
|
||||
- Add .gitignore (optional)
|
||||
- Choose license (optional)
|
||||
4. Click "Create Repository"
|
||||
|
||||
**Cloning a repository**:
|
||||
```bash
|
||||
git clone https://git.parkingmeter.info/owner/repo.git
|
||||
cd repo
|
||||
```
|
||||
|
||||
### 2. Branch Management
|
||||
|
||||
**Creating a branch**:
|
||||
```bash
|
||||
git checkout -b feature/new-feature
|
||||
git push -u origin feature/new-feature
|
||||
```
|
||||
|
||||
**In Gitea UI**:
|
||||
1. Go to repository
|
||||
2. Click branch dropdown
|
||||
3. Type new branch name
|
||||
4. Click "Create Branch"
|
||||
|
||||
### 3. Pull Requests
|
||||
|
||||
**Creating a Pull Request**:
|
||||
1. Push branch to Gitea
|
||||
2. Click "New Pull Request" button (appears after push)
|
||||
3. Select base branch (usually `main` or `master`)
|
||||
4. Fill in PR title and description
|
||||
5. Add reviewers, labels, milestones if needed
|
||||
6. Click "Create Pull Request"
|
||||
|
||||
**PR Workflow** (same as GitHub):
|
||||
- Review code
|
||||
- Add comments
|
||||
- Request changes
|
||||
- Approve
|
||||
- Merge (merge, squash, or rebase)
|
||||
|
||||
### 4. Issues
|
||||
|
||||
**Creating an Issue**:
|
||||
1. Go to repository
|
||||
2. Click "Issues" tab
|
||||
3. Click "New Issue"
|
||||
4. Fill in title and description
|
||||
5. Add labels, assignees, milestones
|
||||
6. Click "Submit new issue"
|
||||
|
||||
**Issue Features**:
|
||||
- Assign to team members
|
||||
- Link to milestones
|
||||
- Add labels
|
||||
- Set due dates
|
||||
- Track dependencies
|
||||
- Reference commits and PRs
|
||||
|
||||
### 5. Gitea Actions (CI/CD)
|
||||
|
||||
**Setting up workflows**:
|
||||
1. Create `.github/workflows/` directory
|
||||
2. Create workflow YAML file
|
||||
3. Push to repository
|
||||
4. Gitea Actions will execute workflows
|
||||
|
||||
**Workflow triggers**:
|
||||
- `push` - On push to repository
|
||||
- `pull_request` - On PR events
|
||||
- `workflow_dispatch` - Manual trigger
|
||||
- `schedule` - Scheduled runs
|
||||
|
||||
**Example workflow**:
|
||||
```yaml
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Run tests
|
||||
run: cargo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Branch Naming
|
||||
|
||||
**Conventions**:
|
||||
- `feature/description` - New features
|
||||
- `fix/description` - Bug fixes
|
||||
- `docs/description` - Documentation
|
||||
- `refactor/description` - Code refactoring
|
||||
- `test/description` - Test improvements
|
||||
|
||||
### 2. Commit Messages
|
||||
|
||||
**Format**: `type(scope): description`
|
||||
|
||||
**Types**:
|
||||
- `feat` - New feature
|
||||
- `fix` - Bug fix
|
||||
- `docs` - Documentation
|
||||
- `chore` - Maintenance
|
||||
- `ci` - CI/CD changes
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
feat(phase-01): Add Zapier integration
|
||||
fix(phase-02): Resolve web link capture
|
||||
docs(kb): add api-auth-decision and update index/changelog
|
||||
```
|
||||
|
||||
### 3. Pull Request Process
|
||||
|
||||
1. **Create feature branch**
|
||||
2. **Make changes and commit**
|
||||
3. **Push branch to Gitea**
|
||||
4. **Create Pull Request**
|
||||
5. **Request review**
|
||||
6. **Address feedback**
|
||||
7. **Merge when approved**
|
||||
|
||||
### 4. Issue Management
|
||||
|
||||
- Use labels for categorization
|
||||
- Link issues to milestones
|
||||
- Reference issues in commits: `Fixes #123`
|
||||
- Close issues via PR: `Closes #123`
|
||||
|
||||
---
|
||||
|
||||
## For LLMs: Workflow Documentation
|
||||
|
||||
### When Documenting Workflows
|
||||
|
||||
**Use Gitea terminology**:
|
||||
```markdown
|
||||
## Development Workflow
|
||||
|
||||
1. Create a feature branch: `git checkout -b feature/name`
|
||||
2. Make changes and commit
|
||||
3. Push to Gitea: `git push origin feature/name`
|
||||
4. Create Pull Request in Gitea
|
||||
5. Request review and address feedback
|
||||
6. Merge when approved
|
||||
```
|
||||
|
||||
**Reference Gitea Actions**:
|
||||
```markdown
|
||||
## CI/CD Workflow
|
||||
|
||||
This repository uses **Gitea Actions** for continuous integration.
|
||||
|
||||
**Note**: Gitea Actions is compatible with GitHub Actions, so workflows
|
||||
use the same YAML format and `.github/workflows/` directory structure.
|
||||
|
||||
Workflows run automatically on:
|
||||
- Push to main branch
|
||||
- Pull requests
|
||||
- Manual trigger via `workflow_dispatch`
|
||||
```
|
||||
|
||||
### When Creating Workflow Files
|
||||
|
||||
**Location and format**:
|
||||
- Use `.github/workflows/` directory
|
||||
- Use standard GitHub Actions YAML format
|
||||
- Reference as "Gitea Actions workflows" in documentation
|
||||
|
||||
**Example**:
|
||||
```yaml
|
||||
# Gitea Actions workflow
|
||||
# Compatible with GitHub Actions format
|
||||
name: Test
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Run tests
|
||||
run: cargo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Documentation System
|
||||
|
||||
### Phase Documentation
|
||||
|
||||
When working with phase documentation:
|
||||
- Reference Gitea repository URLs
|
||||
- Use Gitea terminology in tasks.md
|
||||
- Link to Gitea issues in tasks
|
||||
- Reference Gitea Actions workflows
|
||||
|
||||
### KB System
|
||||
|
||||
When creating KB entries:
|
||||
- Reference Gitea features when relevant
|
||||
- Link to Gitea documentation
|
||||
- Use Gitea terminology consistently
|
||||
|
||||
### Cursor Rules
|
||||
|
||||
When updating Cursor rules:
|
||||
- Use "Gitea Actions" (not "GitHub Actions")
|
||||
- Reference Gitea repository
|
||||
- Note compatibility where relevant
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Workflow not running**:
|
||||
- Check runner registration
|
||||
- Verify workflow syntax
|
||||
- Check trigger conditions
|
||||
- Review runner logs
|
||||
|
||||
**PR not showing**:
|
||||
- Verify branch was pushed
|
||||
- Check branch visibility
|
||||
- Verify base branch is correct
|
||||
|
||||
**Issues not linking**:
|
||||
- Use correct issue number format: `#123`
|
||||
- Verify issue exists
|
||||
- Check repository permissions
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Gitea Usage**: https://docs.gitea.com/usage/
|
||||
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
|
||||
- **Pull Requests**: https://docs.gitea.com/usage/pull-request/
|
||||
- **Issues**: https://docs.gitea.com/usage/issues/
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/GITEA/Gitea-Workflows.md`
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
220
docs/GITEA/LLM-Gitea-Guidelines.md
Normal file
220
docs/GITEA/LLM-Gitea-Guidelines.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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**:
|
||||
```markdown
|
||||
This repository uses **Gitea** for version control and collaboration.
|
||||
```
|
||||
|
||||
2. **Actions Reference**:
|
||||
```markdown
|
||||
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**:
|
||||
```markdown
|
||||
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**:
|
||||
```yaml
|
||||
# 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:
|
||||
```markdown
|
||||
#### When Gitea Actions workflows (`.github/workflows/*.yml`) are modified:
|
||||
```
|
||||
|
||||
2. **Note compatibility**:
|
||||
```markdown
|
||||
**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**:
|
||||
```markdown
|
||||
### 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**:
|
||||
```markdown
|
||||
**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**:
|
||||
```markdown
|
||||
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`
|
||||
|
||||
106
docs/GITEA/README.md
Normal file
106
docs/GITEA/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Gitea Documentation for LLMs
|
||||
|
||||
**Purpose**: This directory contains documentation to help AI assistants (LLMs) understand and work with Gitea, a self-hosted Git service.
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Gitea** is a painless, self-hosted, all-in-one software development service. It includes Git hosting, code review, team collaboration, package registry, and CI/CD. It is similar to GitHub, Bitbucket and GitLab.
|
||||
|
||||
**Key Reference**: [Gitea Official Documentation](https://docs.gitea.com/)
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
- **[Gitea-Basics.md](./Gitea-Basics.md)** - Core concepts, features, and how Gitea differs from GitHub
|
||||
- **[Gitea-Actions-Guide.md](./Gitea-Actions-Guide.md)** - Gitea Actions (CI/CD) compatibility and usage
|
||||
- **[Gitea-Workflows.md](./Gitea-Workflows.md)** - Common workflows and best practices
|
||||
- **[Gitea-API-Reference.md](./Gitea-API-Reference.md)** - API differences and considerations
|
||||
- **[LLM-Gitea-Guidelines.md](./LLM-Gitea-Guidelines.md)** - Guidelines for LLMs working with Gitea
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### What is Gitea?
|
||||
|
||||
Gitea is a self-hosted Git service that provides:
|
||||
- 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)
|
||||
- Team collaboration tools
|
||||
|
||||
### Key Differences from GitHub
|
||||
|
||||
1. **Self-Hosted**: Gitea runs on your own infrastructure
|
||||
2. **Lightweight**: Designed to be fast and resource-efficient
|
||||
3. **Open Source**: MIT licensed, community-driven
|
||||
4. **Actions Compatibility**: Gitea Actions uses the same YAML format as GitHub Actions
|
||||
5. **API Compatibility**: Gitea API is similar to GitHub's but has some differences
|
||||
|
||||
### Gitea Actions Compatibility
|
||||
|
||||
**Critical**: Gitea Actions is compatible with GitHub Actions:
|
||||
- Same `.github/workflows/` directory structure
|
||||
- Same YAML workflow format
|
||||
- Same triggers and syntax
|
||||
- Existing GitHub Actions workflows work with minimal or no modifications
|
||||
- Actions plugins can be downloaded from any Git website
|
||||
|
||||
**Reference**: [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)
|
||||
|
||||
---
|
||||
|
||||
## For LLMs Working with Gitea
|
||||
|
||||
### Terminology
|
||||
|
||||
- Use **"Gitea"** (not "GitHub") when referring to the platform
|
||||
- Use **"Gitea Actions"** (not "GitHub Actions") but note compatibility
|
||||
- Use **"Pull Request"** or **"PR"** (same as GitHub)
|
||||
- Use **"Issues"** (same as GitHub)
|
||||
- Use **"Repository"** or **"Repo"** (same as GitHub)
|
||||
|
||||
### Documentation References
|
||||
|
||||
When creating documentation:
|
||||
- Reference Gitea-specific features when relevant
|
||||
- Note GitHub Actions compatibility when discussing workflows
|
||||
- Use Gitea terminology consistently
|
||||
- Link to Gitea documentation: `https://docs.gitea.com/`
|
||||
|
||||
### Workflow Files
|
||||
|
||||
- Workflows use `.github/workflows/` directory (same as GitHub)
|
||||
- YAML format is identical to GitHub Actions
|
||||
- Reference as "Gitea Actions workflows" in documentation
|
||||
- Note compatibility: "Gitea Actions is compatible with GitHub Actions"
|
||||
|
||||
---
|
||||
|
||||
## Repository Context
|
||||
|
||||
**Tendril Repository**: https://git.parkingmeter.info/Mycelium/tendril
|
||||
**Gitea Instance**: Self-hosted at git.parkingmeter.info
|
||||
**Primary Platform**: Gitea (not GitHub)
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Official Gitea Docs**: https://docs.gitea.com/
|
||||
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
|
||||
- **Gitea API**: https://docs.gitea.com/api/
|
||||
- **Gitea Source**: https://gitea.com/gitea/gitea
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/GITEA/`
|
||||
**Maintained by**: Tendril Project Maintainers
|
||||
|
||||
2437
docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
Normal file
2437
docs/PHASE-UPDATES/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
Normal file
File diff suppressed because it is too large
Load Diff
62
docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md
Normal file
62
docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Phase 0 Gitea Updates Summary
|
||||
|
||||
**Date**: 2025-01-27
|
||||
**Purpose**: Document updates made to Phase 0 files to reflect Gitea (self-hosted) instead of GitHub
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. `.cursorrules` File Updates
|
||||
|
||||
**Updated References:**
|
||||
- "GitHub Actions workflows" → "Gitea Actions workflows" (3 occurrences)
|
||||
- "GitHub Actions will auto-update" → "Gitea Actions will auto-update"
|
||||
|
||||
**Note**: Gitea Actions is compatible with GitHub Actions, so the `.github/workflows/` directory structure and YAML format remain the same.
|
||||
|
||||
### 2. `docs/AGENT-GUIDELINES.md` Updates
|
||||
|
||||
**Updated References:**
|
||||
- "GitHub issues" → "Gitea issues"
|
||||
- "GitHub Automation" → "Gitea Automation" (section title)
|
||||
- "GitHub Actions workflows" → "Gitea Actions workflows (compatible with GitHub Actions format)"
|
||||
- "When Modifying GitHub Workflows" → "When Modifying Gitea Actions Workflows"
|
||||
- Added note: "Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure."
|
||||
- Added note: "Gitea Actions workflows use the same YAML format as GitHub Actions, so existing GitHub Actions workflows can be used with minimal or no modifications."
|
||||
- "GitHub automation" → "Gitea automation" (in Getting Help section)
|
||||
|
||||
## Key Points
|
||||
|
||||
1. **Gitea Actions Compatibility**: Gitea Actions is compatible with GitHub Actions, meaning:
|
||||
- Same `.github/workflows/` directory structure
|
||||
- Same YAML workflow format
|
||||
- Same triggers and syntax
|
||||
- Existing GitHub Actions workflows can be used with minimal or no modifications
|
||||
|
||||
2. **Repository Context**:
|
||||
- Primary repository: https://git.parkingmeter.info/Mycelium/tendril (Gitea)
|
||||
- Self-hosted Gitea instance
|
||||
- Uses Gitea Actions for CI/CD automation
|
||||
|
||||
3. **No Structural Changes Needed**:
|
||||
- Directory structure remains the same
|
||||
- Workflow files will work as-is
|
||||
- Only documentation references needed updating
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. `.cursorrules` - Updated 3 references from GitHub to Gitea
|
||||
2. `docs/AGENT-GUIDELINES.md` - Updated 6 references and added compatibility notes
|
||||
|
||||
## Next Steps
|
||||
|
||||
When creating workflows in Phase 3:
|
||||
- Use standard GitHub Actions YAML format
|
||||
- Workflows will work with Gitea Actions automatically
|
||||
- Reference "Gitea Actions" in documentation, but note GitHub Actions compatibility
|
||||
- Test workflows in Gitea Actions interface (similar to GitHub Actions tab)
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/PHASE-UPDATES/PHASE-0-GITEA-UPDATES.md`
|
||||
**Related**: Phase 0 setup, Gitea Actions compatibility
|
||||
|
||||
59
docs/PHASE-UPDATES/README.md
Normal file
59
docs/PHASE-UPDATES/README.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Phase Updates Documentation
|
||||
|
||||
**Purpose**: This directory contains documentation related to phase updates, system replication guides, and migration notes.
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
### System Replication
|
||||
|
||||
- **[COMPLETE-SYSTEM-REPLICATION-GUIDE.md](./COMPLETE-SYSTEM-REPLICATION-GUIDE.md)** - Comprehensive guide for replicating the PAIRS documentation and automation system in another project. Includes all structures, schemas, templates, rationale, and step-by-step instructions.
|
||||
|
||||
### Phase Updates
|
||||
|
||||
- **[PHASE-0-GITEA-UPDATES.md](./PHASE-0-GITEA-UPDATES.md)** - Documents updates made to Phase 0 files to reflect Gitea (self-hosted) instead of GitHub. Includes changes to `.cursorrules` and `docs/AGENT-GUIDELINES.md`.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This directory serves as a reference for:
|
||||
|
||||
1. **System Replication**: Complete guide for setting up the documentation and automation system in new projects
|
||||
2. **Phase Updates**: Tracking changes and updates made during each phase of project setup
|
||||
3. **Migration Notes**: Documenting platform-specific adaptations (e.g., Gitea vs GitHub)
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### For System Replication
|
||||
|
||||
If you want to replicate this documentation system in another project:
|
||||
1. Read `COMPLETE-SYSTEM-REPLICATION-GUIDE.md`
|
||||
2. Follow the step-by-step replication guide
|
||||
3. Customize for your project's needs
|
||||
|
||||
### For Phase Updates
|
||||
|
||||
When making updates during phase setup:
|
||||
1. Document changes in phase-specific update files
|
||||
2. Reference these files when reviewing phase work
|
||||
3. Use as historical record of decisions made
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Agent Guidelines**: `docs/AGENT-GUIDELINES.md` - Guidelines for AI agents
|
||||
- **Gitea Documentation**: `docs/GITEA/` - Gitea-specific documentation
|
||||
- **Phase Documentation**: `tendril/phases/` - Phase blueprints and related docs
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/PHASE-UPDATES/`
|
||||
**Maintained by**: Tendril Project Maintainers
|
||||
|
||||
Reference in New Issue
Block a user