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:
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
|
||||
|
||||
Reference in New Issue
Block a user