Files

Gitea Actions 1423ee1f04 fix(workflows): resolve git revision error in KB lint workflow

- Fix HEAD~1...HEAD error for shallow clones by using github.event.before/after
- Add proper error suppression with 2>/dev/null
- Add fallback logic for edge cases (initial commits, force pushes)
- Archive resolved runner setup issue to docs/issues/archive/resolved/
- Add archive documentation and next steps guide

Fixes workflow execution on test/runner-validation branch.
Resolves issue with 'fatal: bad revision' error in logs.

2025-11-11 14:46:26 -07:00

README.md

Issues Capture System

Quick capture system for potential insights, problems, structural changes, bugs, and features

Purpose

The docs/issues/ folder is a lightweight staging area for capturing issues, ideas, and problems as you encounter them. These markdown files can be quickly created and filled out, then later compiled into actual Gitea issues for project boards.

Key Benefits:

⚡ Quick capture - Minimal fields, fast to fill out
📝 Markdown-based - Easy to edit and version control
🔄 Later compilation - Can be batch-processed into Gitea issues
📊 Searchable - All issues in one place, easy to review

Workflow

1. Quick Capture

When you encounter an issue, insight, bug, or feature idea:

Copy template.md to create a new issue file
Use filename format: YYYY-MM-DD--short-description.md
Fill out the minimal required fields
Save and commit

2. Regular Review

Periodically review issues in this folder:

Group related issues
Prioritize by impact
Identify patterns or themes

3. Compilation to Gitea Issues

When ready to create actual Gitea issues:

Review all issues in this folder
Create Gitea issues from the markdown files
Link back to the original markdown file
Optionally archive or move processed issues

File Naming

Use format: YYYY-MM-DD--short-description.md

Examples:

2025-11-11--gitea-runner-setup.md
2025-11-11--add-mentions-field.md
2025-11-11--kb-routing-improvement.md

Issue Types

Use the type field in the template to categorize:

bug - Something broken or not working correctly
feature - New functionality or enhancement
insight - Observation or pattern noticed
structural - Changes to project structure or architecture
improvement - Enhancement to existing functionality
question - Something to investigate or clarify

Template Fields

The template includes minimal required fields:

Title - Brief, descriptive title
Type - Category (bug, feature, insight, etc.)
Date - When issue was captured
Description - What the issue/idea is
Impact - Why it matters (optional)
Notes - Additional context (optional)

Keep it simple - you can always add more detail later when creating the Gitea issue.

Best Practices

Capture quickly - Don't overthink, just get it down
One issue per file - Makes compilation easier
Use descriptive filenames - Helps with search and review
Add context - Include enough detail to remember later
Review regularly - Don't let issues pile up indefinitely

Future Automation

Potential enhancements:

Script to batch-create Gitea issues from markdown files
Gitea Actions workflow to auto-create issues on file creation
Integration with project boards
Automated categorization and tagging

Platform Notes

Gitea-Specific:

Repository: https://git.parkingmeter.info/Mycelium/tendril
Platform: Gitea (self-hosted)
Issues: Gitea issues (compatible with GitHub issues format)
See docs/GITEA/Gitea-Basics.md for Gitea-specific guidance

Location: docs/issues/
Related:

docs/GITEA/Gitea-Basics.md - Gitea platform basics
docs/GITEA/Gitea-Workflows.md - Gitea workflows and best practices