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