From d49719c39441619a96508fdc1b2105dfb0da291f Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Tue, 17 Feb 2026 03:05:10 +0000 Subject: [PATCH] docs: Add comprehensive documentation for workflows and automation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create docs/ directory with structured documentation - Add Getting Started guide for new repository users - Add Labels Guide explaining the label system - Add Automation Overview explaining all automated workflows - Add Workflow Reference with technical workflow details - Update main README with links to documentation These docs provide: - Onboarding guidance for new team members - Explanation of agentic vs standard workflows - Best practices for using labels - Troubleshooting guides for workflows - Clear structure following DiΓ‘taxis framework Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 10 + docs/README.md | 49 +++ docs/automation-overview.md | 452 ++++++++++++++++++++ docs/getting-started.md | 171 ++++++++ docs/labels-guide.md | 260 ++++++++++++ docs/workflow-reference.md | 796 ++++++++++++++++++++++++++++++++++++ 6 files changed, 1738 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/automation-overview.md create mode 100644 docs/getting-started.md create mode 100644 docs/labels-guide.md create mode 100644 docs/workflow-reference.md diff --git a/README.md b/README.md index 1d30ed8..049dac1 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,16 @@ This repository organizes our farm records into four sections: Use this repository to find any farm document. Click a folder to explore. +## New to This Repository? + +πŸ‘‰ **Start with the [Getting Started Guide](./docs/getting-started.md)** for setup and basic workflows. + +**Key Documentation:** +- πŸ“– [Getting Started](./docs/getting-started.md) - First steps and common workflows +- 🏷️ [Labels Guide](./docs/labels-guide.md) - Using labels to organize work +- πŸ€– [Automation Overview](./docs/automation-overview.md) - Understanding automated workflows +- βš™οΈ [Workflow Reference](./docs/workflow-reference.md) - Technical workflow documentation + --- ## Quick Links diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e049491 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ +# Documentation Guide + +This directory contains comprehensive documentation for the Sunny Acres Farm repository. + +## Quick Start + +New to this repository? Start here: + +1. **[Getting Started Guide](./getting-started.md)** - Setup and first steps +2. **[Automation Overview](./automation-overview.md)** - Understanding automated workflows +3. **[Labels Guide](./labels-guide.md)** - Using labels effectively + +## Documentation Structure + +### For Users + +| Guide | Purpose | +|-------|---------| +| [Getting Started](./getting-started.md) | Onboarding and basic workflows | +| [Labels Guide](./labels-guide.md) | Understanding and using repository labels | +| [Automation Overview](./automation-overview.md) | How automated workflows help manage the farm | + +### For Contributors + +| Guide | Purpose | +|-------|---------| +| [Workflow Reference](./workflow-reference.md) | Detailed workflow documentation | + +## Farm Operations Documentation + +Primary farm records are organized in dedicated directories: + +- **[Crops](../crops/)** - Planting schedules, rotation plans, soil tests +- **[Livestock](../livestock/)** - Health records, feeding schedules, vet logs +- **[Equipment](../equipment/)** - Maintenance logs, safety inspections, inventory +- **[Compliance](../compliance/)** - Grant tracking, certifications + +## Repository Governance + +- **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute updates +- **[Code of Conduct](../CODE_OF_CONDUCT.md)** - Community standards +- **[Support](../SUPPORT.md)** - Getting help +- **[Security](../SECURITY.md)** - Security and privacy practices + +## Need Help? + +- Create an Issue with the appropriate label +- Start a Discussion for questions +- See [SUPPORT.md](../SUPPORT.md) for detailed guidance diff --git a/docs/automation-overview.md b/docs/automation-overview.md new file mode 100644 index 0000000..35decf5 --- /dev/null +++ b/docs/automation-overview.md @@ -0,0 +1,452 @@ +# Automation Overview + +The Sunny Acres Farm repository includes several automated workflows that help manage farm operations, maintain data quality, and streamline collaboration. This guide explains what automation exists and how it helps. + +## Why Automation? + +Farm management involves repetitive tasks, routine checks, and timely reminders. Automation helps by: + +- **Reducing manual overhead** - Automatic reminders and checks +- **Ensuring consistency** - Standard processes every time +- **Catching issues early** - Quality checks on every change +- **Saving time** - Less time on administration, more on farming + +## Automated Workflows + +### 1. Weekly Farm Reminder + +**Purpose:** Creates a weekly checklist every Monday morning + +**What it does:** +- Runs every Monday at 8:00 AM UTC +- Creates an Issue with a farm task checklist +- Labels it `routine` and `maintenance` +- Includes equipment, livestock, crops, and administrative checks + +**How to use it:** +1. Check for the weekly Issue each Monday +2. Work through the checklist +3. Check off items as completed +4. Close the Issue when done or roll tasks to next week + +**Example Issue:** +````markdown +Title: Weekly Farm Check - Week 7 + +Labels: routine, maintenance + +## Weekly Farm Checklist +- [ ] Check fluid levels on all tractors +- [ ] Verify all water sources are working +- [ ] Scout fields for pest or disease signs +- [ ] Review any open issues from last week +```` + +**Triggering manually:** +- Go to **Actions** tab +- Select "Weekly Farm Reminder" +- Click **Run workflow** + +--- + +### 2. Issue Triage + +**Purpose:** Automatically categorizes and prioritizes new Issues + +**What it does:** +- Runs when a new Issue is created +- Analyzes the Issue title and description +- Suggests appropriate labels (domain, type, priority) +- Adds helpful comments with guidance +- Can assign Issues to team members based on area + +**How it helps:** +- Ensures Issues are properly labeled +- Routes Issues to the right people +- Identifies urgent matters quickly +- Maintains organization automatically + +**What you'll see:** +After creating an Issue, the bot may add: +- Suggested labels +- A comment explaining the triage +- Assignment to a relevant team member + +**Note:** You can modify the automated suggestions if they're incorrect. + +--- + +### 3. Daily QA (Quality Assurance) + +**Purpose:** Performs nightly data quality checks + +**What it does:** +- Runs daily at 2:00 AM UTC +- Checks for common issues: + - Broken links in documentation + - Missing required fields in records + - Outdated information (e.g., expired certifications) + - Inconsistent formatting + - Missing cross-references +- Creates Issues for problems found +- Labels them `automation` and `qa` + +**How it helps:** +- Catches data drift before it becomes a problem +- Maintains documentation accuracy +- Flags outdated compliance records +- Ensures file integrity + +**What you'll see:** +Issues created by Daily QA might look like: +````markdown +Title: [QA] Broken link in equipment/maintenance-log.md + +Labels: automation, qa, equipment, documentation + +The link to the parts vendor catalog is broken. +Please update or remove it. +```` + +**Responding to QA Issues:** +1. Review the identified problem +2. Fix the issue +3. Close the QA Issue +4. The next nightly run will verify the fix + +--- + +### 4. Update Docs + +**Purpose:** Keeps documentation synchronized with repository changes + +**What it does:** +- Runs on every push to the main branch +- Analyzes what changed +- Identifies documentation that needs updates +- Creates a Pull Request with suggested documentation changes +- Labels PRs as `automation` and `documentation` + +**How it helps:** +- Documentation stays current +- Reduces manual documentation work +- Ensures changes are reflected in guides +- Maintains single source of truth + +**What you'll see:** +After merging changes, you may see a draft PR: +````markdown +Title: Update docs to reflect new planting schedule structure + +Labels: automation, documentation + +## Changes +- Updated crops/README.md to reflect new schedule format +- Added section to getting-started.md about scheduling +- Cross-referenced new fields in planting-schedule.md +```` + +**Responding to doc updates:** +1. Review the suggested changes +2. Make any needed adjustments +3. Mark the PR as "Ready for review" +4. Merge when approved + +--- + +### 5. CI Doctor + +**Purpose:** Monitors the health of automated workflows themselves + +**What it does:** +- Runs when workflows fail +- Diagnoses common workflow problems +- Suggests fixes for failures +- Creates Issues for recurring problems +- Labels them `automation` and `ci` + +**How it helps:** +- Keeps automation working smoothly +- Identifies configuration problems +- Provides troubleshooting guidance +- Maintains workflow reliability + +**What you'll see:** +Issues from CI Doctor look like: +````markdown +Title: [CI] Weekly Reminder workflow failed + +Labels: automation, ci + +The weekly reminder workflow failed due to permissions. +Suggested fix: Update workflow permissions in .github/workflows/weekly-reminder.yml +```` + +**Responding to CI issues:** +- Repository maintainers will typically handle these +- You may be asked to re-run a failed workflow +- Report repeated failures in Discussions + +--- + +### 6. Dependabot Auto-Merge + +**Purpose:** Automatically updates and merges dependency updates + +**What it does:** +- Monitors for security updates +- Automatically approves and merges safe updates +- Requires CI checks to pass first +- Focuses on patch and minor version updates + +**How it helps:** +- Keeps dependencies secure +- Reduces manual update burden +- Maintains compatibility +- Prevents security vulnerabilities + +**What you'll see:** +Dependabot may create PRs like: +````markdown +Title: Bump actions/checkout from 3.5.0 to 3.5.2 + +Labels: dependencies + +Automatically merged after CI passed. +```` + +**When it won't auto-merge:** +- Major version updates (require manual review) +- Breaking changes detected +- CI checks fail +- Conflicts with other changes + +--- + +## Workflow Labels + +Automated workflows use specific labels: + +| Label | Applied By | Meaning | +|-------|-----------|---------| +| `automation` | All workflows | Created by automation | +| `documentation` | Update Docs | Documentation changes | +| `qa` | Daily QA | Quality assurance issue | +| `ci` | CI Doctor | Workflow health issue | +| `dependencies` | Dependabot | Dependency update | + +**Tip:** Filter Issues by `label:automation` to see all automated activity. + +## Viewing Workflow Runs + +### See Recent Workflow Activity + +1. Go to the **Actions** tab +2. View all recent workflow runs +3. Click any run for detailed logs +4. Check status: βœ… Success, ❌ Failed, πŸ”„ In Progress + +### Check a Specific Workflow + +1. **Actions** tab β†’ Left sidebar +2. Select workflow (e.g., "Weekly Farm Reminder") +3. View run history +4. See success rate and timing + +### Manually Trigger Workflows + +Some workflows can be run manually: + +1. **Actions** tab +2. Select the workflow +3. Click **Run workflow** button +4. Choose branch (usually `main`) +5. Click **Run workflow** + +**Manually triggerable workflows:** +- Weekly Farm Reminder +- Daily QA +- Update Docs + +## Understanding Workflow Files + +Workflows are defined in `.github/workflows/`: + +| File | Type | Purpose | +|------|------|---------| +| `weekly-reminder.yml` | Standard | Creates weekly checklists | +| `dependabot-automerge.yml` | Standard | Auto-merges dependencies | +| `issue-triage.md` | Agentic | AI-powered issue categorization | +| `daily-qa.md` | Agentic | Intelligent quality checks | +| `update-docs.md` | Agentic | Smart documentation updates | +| `ci-doctor.md` | Agentic | Workflow health diagnostics | +| `q.md` | Agentic | General query and assistance | + +### Standard vs. Agentic Workflows + +**Standard workflows** (`.yml` files): +- Traditional GitHub Actions +- Follow scripted logic +- Predictable behavior +- Fast execution + +**Agentic workflows** (`.md` files): +- AI-powered automation +- Understand context and intent +- Adaptive responses +- More intelligent decisions + +## Workflow Schedule + +| Workflow | When it Runs | +|----------|-------------| +| Weekly Reminder | Every Monday, 8:00 AM UTC | +| Daily QA | Every day, 2:00 AM UTC | +| Issue Triage | On new Issue creation | +| Update Docs | On push to main branch | +| CI Doctor | When workflows fail | +| Dependabot | Weekly, or when updates available | + +## Customizing Automation + +### Adjusting the Weekly Checklist + +Edit `.github/workflows/weekly-reminder.yml`: + +1. Create a branch +2. Edit the `body:` section (lines 37-63) +3. Add, remove, or modify checklist items +4. Submit a Pull Request +5. Test the changes + +### Changing Workflow Schedules + +Edit the `cron:` line in workflow files: + +````yaml +schedule: + - cron: '0 8 * * 1' # Monday at 8 AM UTC +```` + +**Cron format:** `minute hour day-of-month month day-of-week` + +**Examples:** +- `0 8 * * 1` - Every Monday at 8 AM +- `0 2 * * *` - Every day at 2 AM +- `0 0 * * 0` - Every Sunday at midnight + +**Important:** Use UTC time zone. + +### Disabling a Workflow + +To temporarily disable: + +1. Go to **Actions** tab +2. Select the workflow +3. Click **β‹―** (three dots) +4. Click **Disable workflow** + +Re-enable the same way. + +## Best Practices + +### Do: + +βœ… **Review automated Issues** - Don't ignore them +βœ… **Close Issues when resolved** - Keep things tidy +βœ… **Provide feedback** - Comment if automation is wrong +βœ… **Check Actions tab** - Monitor workflow health +βœ… **Update templates** - Keep checklists relevant + +### Don't: + +❌ **Auto-close automation Issues** - Review them first +❌ **Ignore failed workflows** - They may need attention +❌ **Delete automated PRs** - Review and merge or decline +❌ **Disable workflows permanently** - Discuss alternatives first + +## Troubleshooting + +### Workflow Didn't Run + +**Check:** +1. Is the workflow enabled? (Actions tab) +2. Was the trigger condition met? (e.g., Monday for weekly reminder) +3. Are there permission issues? (Check CI Doctor) +4. Is the repository active? (Disabled on inactive repos) + +### Automated Issue is Wrong + +**If automation mislabeled an Issue:** +1. Correct the labels manually +2. Add a comment explaining why +3. The workflow learns from corrections + +**If automation created a duplicate:** +1. Close the duplicate +2. Reference the original +3. Report in Discussions if it recurs + +### Workflow Failed + +**Steps:** +1. Check the **Actions** tab for error details +2. Look for CI Doctor Issues with guidance +3. Try re-running the workflow +4. Report persistent failures in Discussions + +## Privacy and Security + +**Workflows cannot:** +- Access private files without permissions +- Modify files outside the repository +- Access sensitive credentials +- Make destructive changes without review + +**All automated changes:** +- Are visible in Pull Requests +- Require review before merging (documentation updates) +- Can be reverted like any commit +- Are logged in workflow runs + +## Learning More + +### Workflow Documentation Files + +Each agentic workflow has detailed documentation: + +- `.github/workflows/issue-triage.md` +- `.github/workflows/daily-qa.md` +- `.github/workflows/update-docs.md` +- `.github/workflows/ci-doctor.md` +- `.github/workflows/q.md` + +### GitHub Actions Documentation + +- [GitHub Actions overview](https://docs.github.com/actions) +- [Workflow syntax](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) +- [Scheduled workflows](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#schedule) + +### Getting Help + +- Create an Issue labeled `question` and `automation` +- Start a Discussion about workflow behavior +- Check [SUPPORT.md](../SUPPORT.md) for contacts + +## Summary + +Automation in this repository: + +1. **Reduces manual work** with weekly reminders and automatic checks +2. **Maintains quality** through daily QA and documentation updates +3. **Improves organization** with automatic issue triage +4. **Keeps systems healthy** with CI Doctor monitoring +5. **Enhances security** with automatic dependency updates + +**Key takeaway:** Automation handles routine tasks so you can focus on farming. Review automated Issues and PRs, but trust the system to maintain quality and consistency. + +## Related Documentation + +- [Getting Started Guide](./getting-started.md) - Repository basics +- [Labels Guide](./labels-guide.md) - Understanding labels used by automation +- [Workflow Reference](./workflow-reference.md) - Technical workflow details diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..57db5ce --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,171 @@ +# Getting Started with Sunny Acres Farm Repository + +Welcome to the Sunny Acres Farm repository! This guide helps you understand the repository structure and start contributing farm records. + +## What This Repository Does + +This repository organizes all farm operational records in one searchable, version-controlled location. Think of it as a digital filing cabinet that: + +- Tracks changes over time +- Enables team collaboration +- Provides automated reminders and quality checks +- Creates audit trails for compliance + +## Repository Structure + +```` +sunny-acres-farm/ +β”œβ”€β”€ crops/ # Crop planning and records +β”œβ”€β”€ livestock/ # Animal health and feeding +β”œβ”€β”€ equipment/ # Machinery maintenance +β”œβ”€β”€ compliance/ # Grants and certifications +β”œβ”€β”€ docs/ # This documentation +└── .github/ # Automation and templates +```` + +## Quick Start Tasks + +### 1. Explore the Repository + +Browse each directory to familiarize yourself with the content: + +- **[Crops](../crops/)** - View planting schedules and soil data +- **[Livestock](../livestock/)** - Check feeding schedules and health records +- **[Equipment](../equipment/)** - Review maintenance logs +- **[Compliance](../compliance/)** - Track active grants and certifications + +### 2. Understand Labels + +Labels categorize Issues and Pull Requests. See the **[Labels Guide](./labels-guide.md)** for details. + +Common labels include: + +- **Domain:** `crops`, `livestock`, `equipment`, `compliance` +- **Type:** `maintenance`, `repair`, `inspection`, `planning`, `health` +- **Priority:** `urgent`, `routine`, `seasonal` + +### 3. Create Your First Issue + +To log a farm event or task: + +1. Click **Issues** tab +2. Click **New issue** +3. Choose a template (crop, livestock, or equipment) +4. Fill in the details +5. Add appropriate labels +6. Submit + +**Example:** Logging equipment maintenance + +````markdown +Title: Oil change needed for John Deere 6120M + +Labels: equipment, maintenance, routine + +Body: +The tractor has reached 200 hours since the last oil change. +Need to schedule service this week. +```` + +### 4. Update Existing Records + +To update a farm record file: + +1. Navigate to the file (e.g., `equipment/maintenance-log.md`) +2. Click the **pencil icon** (Edit) +3. Make your changes +4. Scroll down to **Commit changes** +5. Write a clear commit message +6. Choose "Create a new branch" and start a pull request +7. Submit for review + +### 5. Use Discussions for Questions + +For general questions or discussions: + +1. Click **Discussions** tab +2. Click **New discussion** +3. Choose a category +4. Ask your question or start a conversation + +## Automated Features + +This repository includes several automated workflows: + +- **Weekly Reminders** - Creates a checklist every Monday +- **Issue Triage** - Categorizes and prioritizes new issues +- **Daily QA** - Checks for data quality issues +- **Documentation Updates** - Keeps docs synchronized with changes +- **CI Doctor** - Monitors workflow health + +Learn more in the **[Automation Overview](./automation-overview.md)**. + +## Common Workflows + +### Recording Livestock Health Events + +1. Create an Issue using the "Livestock Health Record" template +2. Add labels: `livestock`, `health`, and priority +3. Update the `livestock/health-records.md` file via Pull Request +4. Link the PR to the Issue + +### Planning Crop Planting + +1. Review `crops/planting-schedule.md` +2. Create an Issue with `crops`, `planning`, `seasonal` labels +3. Discuss timing in the Issue comments +4. Update the schedule via Pull Request when finalized + +### Tracking Equipment Repairs + +1. Create an Issue using the "Equipment Maintenance" template +2. Add labels: `equipment`, `repair`, and status (e.g., `waiting-on-parts`) +3. Log service in `equipment/maintenance-log.md` +4. Close the Issue when work is complete + +## Best Practices + +### Write Clear Commit Messages + +**Good:** +- "Update planting dates for North Field corn" +- "Add vet visit for cow #42 - vaccination" +- "Mark tractor oil change complete - 200hr service" + +**Avoid:** +- "Update" +- "Fix stuff" +- "Changes" + +### Use Specific Details + +Include: +- Field names or numbers +- Animal IDs or tag numbers +- Equipment model and serial numbers +- Dates in YYYY-MM-DD format +- Measurements with units + +### Check Before Committing + +- Verify dates and numbers +- Ensure no sensitive personal information +- Review for typos +- Confirm file is in the correct directory + +## Getting Help + +- **Create an Issue** with the `question` label +- **Start a Discussion** for open-ended questions +- **Check [SUPPORT.md](../SUPPORT.md)** for contact information +- **Review [CONTRIBUTING.md](../CONTRIBUTING.md)** for contribution guidelines + +## Next Steps + +1. βœ… Read this Getting Started guide +2. πŸ“‹ Review the [Labels Guide](./labels-guide.md) +3. πŸ€– Understand [Automation Overview](./automation-overview.md) +4. πŸ“ Create your first Issue or update a record +5. πŸ’¬ Introduce yourself in Discussions + +Welcome to the team! 🚜 diff --git a/docs/labels-guide.md b/docs/labels-guide.md new file mode 100644 index 0000000..9f8b28f --- /dev/null +++ b/docs/labels-guide.md @@ -0,0 +1,260 @@ +# Labels Guide + +Labels help organize and prioritize Issues and Pull Requests in the Sunny Acres Farm repository. This guide explains the label system and how to use labels effectively. + +## Label Categories + +Labels are organized into four categories: + +### 1. Domain Labels (What area?) + +Identify which area of the farm the issue relates to: + +| Label | Color | Use When | +|-------|-------|----------| +| `crops` | 🟒 Green | Planting, harvesting, soil, field work | +| `livestock` | 🟀 Brown | Animals, feeding, health, breeding | +| `equipment` | ⚫ Dark Gray | Tractors, tools, machinery, implements | +| `compliance` | πŸ”΅ Blue | Grants, certifications, regulations, reporting | + +**Example:** An issue about corn planting would use the `crops` label. + +### 2. Type Labels (What kind of task?) + +Describe the nature of the work: + +| Label | Color | Use When | +|-------|-------|----------| +| `maintenance` | 🟠 Orange | Routine upkeep and service | +| `repair` | πŸ”΄ Red | Fixing broken equipment or systems | +| `inspection` | 🟑 Yellow | Safety checks, audits, evaluations | +| `planning` | 🟣 Purple | Strategy, scheduling, decision-making | +| `health` | πŸ’— Pink | Animal or plant health concerns | +| `documentation` | πŸ“˜ Blue | Record updates, reports, documentation | + +**Example:** Scheduling an oil change would use `maintenance`. + +### 3. Priority Labels (How urgent?) + +Indicate the urgency level: + +| Label | Color | Use When | +|-------|-------|----------| +| `urgent` | πŸ”΄ Bright Red | Immediate attention required (safety, animal health) | +| `routine` | 🟒 Green | Normal operations, can be scheduled | +| `seasonal` | 🟑 Yellow | Time-sensitive but tied to season/weather | + +**Example:** A broken water line in the livestock barn would be `urgent`. + +### 4. Status Labels (What's the blocker?) + +Track what's preventing progress: + +| Label | Color | Use When | +|-------|-------|----------| +| `waiting-on-parts` | ⚫ Gray | Repair delayed by parts shipment | +| `waiting-on-weather` | 🌧️ Light Blue | Field work delayed by conditions | +| `waiting-on-vet` | 🩺 Light Pink | Veterinary consultation needed | +| `waiting-on-approval` | πŸ“‹ Beige | Decision or authorization pending | + +**Example:** A tractor repair waiting for a fuel pump would use `waiting-on-parts`. + +## Additional Labels + +### Special Purpose Labels + +| Label | Color | Purpose | +|-------|-------|---------| +| `automation` | πŸ€– Light Gray | Created by automated workflows | +| `qa` | πŸ” Light Purple | Quality assurance and checks | +| `ci` | βš™οΈ Dark Gray | Continuous integration workflow issues | +| `good first issue` | πŸ’š Bright Green | Great for newcomers | +| `help wanted` | πŸ™‹ Orange | Extra assistance needed | +| `question` | ❓ Light Blue | Seeking information or clarification | + +## How to Apply Labels + +### When Creating an Issue + +1. Click **New issue** +2. Choose a template (optional) +3. Fill in the issue details +4. On the right sidebar, click **Labels** +5. Select appropriate labels from each category +6. Submit the issue + +**Tip:** Most issues should have at least 2-3 labels (domain + type + priority). + +### When Creating a Pull Request + +1. Create your PR +2. On the right sidebar, click **Labels** +3. Add labels that match the content: + - Domain label for which area is affected + - `documentation` if updating records + - Priority if time-sensitive + +### Updating Labels on Existing Issues + +Anyone with write access can update labels: + +1. Open the Issue or PR +2. Click **Labels** in the right sidebar +3. Add or remove labels as the situation changes +4. Comment to explain significant label changes + +## Label Combinations + +### Common Patterns + +**Equipment repair waiting for parts:** +``` +equipment, repair, routine, waiting-on-parts +``` + +**Urgent livestock health issue:** +``` +livestock, health, urgent +``` + +**Seasonal crop planning:** +``` +crops, planning, seasonal +``` + +**Routine equipment inspection:** +``` +equipment, inspection, routine +``` + +**Compliance documentation update:** +``` +compliance, documentation, routine +``` + +### Status Label Workflow + +Status labels help track blockers: + +1. Issue created β†’ No status label +2. Blocker identified β†’ Add appropriate `waiting-on-*` label +3. Blocker resolved β†’ Remove `waiting-on-*` label +4. Work completed β†’ Close issue + +**Example Timeline:** + +- **Day 1:** Create issue: `equipment, repair, urgent` +- **Day 2:** Parts ordered: Add `waiting-on-parts` +- **Day 5:** Parts arrive: Remove `waiting-on-parts` +- **Day 6:** Repair complete: Close issue + +## Searching by Labels + +### Find All Issues in a Category + +Use the Labels tab or search: + +- All crop issues: Click `crops` label or search `label:crops` +- All urgent tasks: Search `label:urgent is:open` +- Equipment waiting on parts: Search `label:equipment label:waiting-on-parts is:open` + +### Filter Multiple Labels + +Combine labels for precise searches: + +``` +label:livestock label:health label:urgent is:open +``` + +This finds all open, urgent livestock health issues. + +### Exclude Labels + +Find issues without a certain label: + +``` +label:equipment -label:waiting-on-parts is:open +``` + +This finds equipment issues NOT waiting on parts. + +## Label Best Practices + +### Do: + +βœ… **Apply multiple labels** - Use domain + type + priority minimum +βœ… **Update labels** - Change status labels as situations evolve +βœ… **Be specific** - Choose the most accurate labels +βœ… **Use status labels** - Track blockers transparently +βœ… **Comment on changes** - Explain why labels changed + +### Don't: + +❌ **Over-label** - Avoid adding every possible label +❌ **Leave unlabeled** - Every issue should have at least one label +❌ **Forget status updates** - Remove `waiting-on-*` when unblocked +❌ **Contradict priority** - Don't mark routine work as urgent + +## Automated Labeling + +Some workflows automatically add labels: + +- **Issue Triage Workflow:** Suggests labels based on issue content +- **Update Docs Workflow:** Adds `automation` + `documentation` +- **Daily QA Workflow:** Adds `automation` + `qa` +- **CI Doctor Workflow:** Adds `automation` + `ci` + +You can modify automated labels if they're incorrect. + +## Creating New Labels + +Need a label that doesn't exist? + +1. Go to **Issues** β†’ **Labels** +2. Click **New label** +3. Propose the new label in a Discussion first +4. Discuss naming, color, and use case +5. Repository maintainers will create if approved + +**Before creating:** Check if an existing label works. + +## Quick Reference + +### Minimal Labeling + +Every issue should have at minimum: + +1. **One domain label:** crops, livestock, equipment, or compliance +2. **One type label:** maintenance, repair, inspection, planning, health, or documentation +3. **One priority label:** urgent, routine, or seasonal + +### Status Labels (Optional) + +Add when blocked: +- `waiting-on-parts` +- `waiting-on-weather` +- `waiting-on-vet` +- `waiting-on-approval` + +### Example Labels for Common Scenarios + +| Scenario | Labels | +|----------|--------| +| Schedule corn planting | `crops`, `planning`, `seasonal` | +| Broken tractor hydraulic line | `equipment`, `repair`, `urgent` | +| Annual safety inspection | `equipment`, `inspection`, `routine` | +| Cow vaccination record | `livestock`, `health`, `routine` | +| EQIP grant report due | `compliance`, `documentation`, `routine` | +| Field flooded, can't plant | `crops`, `planning`, `waiting-on-weather` | + +## Questions? + +- Create an Issue with the `question` label +- Start a Discussion +- See [SUPPORT.md](../SUPPORT.md) for help + +## Related Documentation + +- [Getting Started Guide](./getting-started.md) - Repository basics +- [Automation Overview](./automation-overview.md) - Automated workflows +- [Labels Configuration](../.github/labels.yml) - Complete label definitions diff --git a/docs/workflow-reference.md b/docs/workflow-reference.md new file mode 100644 index 0000000..6b55949 --- /dev/null +++ b/docs/workflow-reference.md @@ -0,0 +1,796 @@ +# Workflow Reference + +Technical documentation for all automated workflows in the Sunny Acres Farm repository. + +## Overview + +This repository uses two types of workflows: + +1. **Standard GitHub Actions** (`.yml` files) - Traditional scripted workflows +2. **Agentic Workflows** (`.md` files) - AI-powered adaptive workflows + +## Standard Workflows + +### Weekly Farm Reminder + +**File:** `.github/workflows/weekly-reminder.yml` + +**Trigger:** +- Schedule: Every Monday at 8:00 AM UTC +- Manual: workflow_dispatch + +**Permissions:** +- `issues: write` + +**What it does:** + +1. Calculates current week number +2. Creates an Issue with weekly checklist +3. Applies labels: `routine`, `maintenance` +4. Includes sections for: + - Equipment checks + - Livestock monitoring + - Crop/field scouting + - Administrative tasks + +**Customization:** + +To modify the checklist, edit lines 37-63: + +````yaml +body: `## Weekly Farm Checklist +- [ ] Your custom task here +` +```` + +**Schedule modification:** + +Change the cron expression on line 13: + +````yaml +- cron: '0 8 * * 1' # minute hour day month day-of-week +```` + +**Common schedules:** +- `0 8 * * 1` - Monday 8 AM UTC +- `0 6 * * 1` - Monday 6 AM UTC +- `0 8 * * 0` - Sunday 8 AM UTC +- `0 8 1 * *` - First day of month 8 AM UTC + +--- + +### Dependabot Auto-Merge + +**File:** `.github/workflows/dependabot-automerge.yml` + +**Trigger:** +- pull_request_target: opened, synchronize, reopened + +**Permissions:** +- `contents: write` +- `pull-requests: write` + +**What it does:** + +1. Detects Dependabot pull requests +2. Waits for CI checks to pass +3. Automatically approves the PR +4. Enables auto-merge +5. Merges when all checks pass + +**Uses reusable workflow:** + +````yaml +uses: zircote/.github/.github/workflows/reusable-dependabot-automerge.yml@main +```` + +**Security:** + +- Only works for Dependabot PRs +- Requires CI checks to pass +- Respects branch protection rules +- Only merges patch/minor updates (configurable) + +**Repository settings required:** + +1. Enable "Allow auto-merge" in repository settings +2. Configure branch protection for main branch +3. Require status checks before merging + +--- + +## Agentic Workflows + +Agentic workflows use AI to understand context and make intelligent decisions. They are defined in Markdown files and compiled to `.lock.yml` files. + +### Source and Compilation + +**Source:** `githubnext/agentics/workflows/` + +Each `.md` file includes: + +````yaml +source: githubnext/agentics/workflows/.md@ +```` + +**Compilation:** + +After editing a `.md` workflow, recompile: + +````bash +gh aw compile +```` + +This updates the corresponding `.lock.yml` file. + +**Important:** Never edit `.lock.yml` files directly. They are auto-generated. + +--- + +### Issue Triage + +**File:** `.github/workflows/issue-triage.md` + +**Trigger:** +- issues: opened +- workflow_dispatch + +**Permissions:** read-all + +**Safe outputs:** +- create-issue +- create-issue-comment +- Labels: `automation` + +**Tools:** +- GitHub: all toolsets +- Bash: enabled + +**Timeout:** 15 minutes + +**What it does:** + +1. Reads new Issue content +2. Analyzes title and description +3. Determines appropriate domain (crops, livestock, equipment, compliance) +4. Identifies type (maintenance, repair, inspection, etc.) +5. Assesses priority (urgent, routine, seasonal) +6. Suggests labels via comment +7. Can auto-apply labels if configured +8. May assign to team members based on area + +**Customization:** + +Edit the Job Description section in `issue-triage.md` to: +- Adjust label suggestions +- Modify assignment logic +- Add custom triage rules +- Change priority thresholds + +**Example custom instruction:** + +````markdown +## Custom Rules + +- Always mark "water" issues as urgent +- Assign livestock issues to @farmmanager +- Tag seasonal issues with the current season +```` + +--- + +### Daily QA + +**File:** `.github/workflows/daily-qa.md` + +**Trigger:** +- schedule: Daily at 2:00 AM UTC +- workflow_dispatch + +**Permissions:** read-all + +**Safe outputs:** +- create-issue +- Labels: `automation`, `qa` + +**Tools:** +- GitHub: all toolsets +- Web-fetch +- Bash: enabled + +**Timeout:** 30 minutes + +**What it does:** + +1. **Documentation Checks:** + - Validates all markdown files + - Checks for broken links + - Verifies file references + - Ensures formatting consistency + +2. **Data Quality Checks:** + - Checks for required fields in records + - Validates dates are in correct format + - Ensures cross-references are accurate + - Identifies missing metadata + +3. **Compliance Checks:** + - Flags approaching deadlines + - Identifies expired certifications + - Validates grant reporting dates + - Checks required documentation exists + +4. **Creates Issues:** + - One Issue per problem found + - Labels: `automation`, `qa`, and relevant domain + - Includes fix suggestions + - References affected files + +**Customization:** + +Add custom checks in the Job Description: + +````markdown +## Custom QA Rules + +- Verify planting dates are within season windows +- Check animal IDs follow format: [Type][Number] (e.g., BC001) +- Ensure equipment hours are incrementing +- Flag maintenance overdue by >30 days +```` + +--- + +### Update Docs + +**File:** `.github/workflows/update-docs.md` + +**Trigger:** +- push: branches [main] +- workflow_dispatch + +**Permissions:** read-all + +**Safe outputs:** +- create-pull-request +- Draft: true +- Labels: `automation`, `documentation` + +**Tools:** +- GitHub: all toolsets +- Web-fetch +- Bash: enabled + +**Timeout:** 15 minutes + +**What it does:** + +1. **Analyzes Changes:** + - Detects files modified in last push + - Identifies new functionality or data + - Determines impact on documentation + +2. **Identifies Documentation Gaps:** + - Checks if related docs exist + - Verifies docs are up-to-date + - Identifies missing cross-references + - Finds outdated examples + +3. **Updates Documentation:** + - Modifies affected documentation files + - Adds new sections as needed + - Updates cross-references + - Maintains consistent style + +4. **Creates Pull Request:** + - Draft PR with documentation changes + - Clear description of what was updated + - Links to the original changes + - Labels: `automation`, `documentation` + +**Documentation Standards:** + +The workflow follows: +- **DiΓ‘taxis framework:** Tutorials, how-to guides, reference, explanation +- **Google Developer Style Guide:** Clear, concise, active voice +- **Microsoft Writing Style Guide:** Accessibility and inclusivity +- **Progressive disclosure:** High-level first, details second + +**Customization:** + +Customize the Job Description section to: +- Add farm-specific documentation rules +- Define custom documentation structure +- Specify required sections +- Set style preferences + +**Example:** + +````markdown +## Farm Documentation Rules + +- Always include field names in crop documentation +- Use YYYY-MM-DD date format +- Include animal IDs in livestock records +- Specify equipment model and serial numbers +```` + +--- + +### CI Doctor + +**File:** `.github/workflows/ci-doctor.md` + +**Trigger:** +- workflow_run: completed (on failure) +- workflow_dispatch + +**Permissions:** read-all + +**Safe outputs:** +- create-issue +- Labels: `automation`, `ci` + +**Tools:** +- GitHub: all toolsets +- Bash: enabled + +**Timeout:** 15 minutes + +**What it does:** + +1. **Detects Workflow Failures:** + - Monitors all workflow runs + - Triggers when any workflow fails + - Retrieves failure logs + +2. **Diagnoses Problems:** + - Analyzes error messages + - Identifies common issues: + - Permission problems + - Missing secrets + - Syntax errors + - Timeout issues + - Dependency failures + +3. **Suggests Fixes:** + - Provides specific remediation steps + - Links to relevant documentation + - Offers configuration examples + - Recommends preventive measures + +4. **Creates Issues:** + - One Issue per failing workflow + - Labels: `automation`, `ci` + - Includes error logs + - Suggests fixes + +**Common Issues Diagnosed:** + +| Problem | Suggested Fix | +|---------|--------------| +| Permission denied | Update workflow permissions | +| Secret not found | Add secret in repository settings | +| Timeout | Increase timeout-minutes | +| Syntax error | Link to line with syntax problem | +| Dependency failure | Update dependency versions | + +**Customization:** + +Add farm-specific CI rules: + +````markdown +## Custom CI Rules + +- If weekly reminder fails, notify @farmmanager +- Timeout after 10 minutes for QA checks +- Retry failed workflows once before creating Issue +```` + +--- + +### Q (Query Assistant) + +**File:** `.github/workflows/q.md` + +**Trigger:** +- issues: opened (with `/q` command) +- issue_comment: created (with `/q` command) +- workflow_dispatch + +**Permissions:** read-all + +**Safe outputs:** +- create-issue-comment +- Labels: `automation` + +**Tools:** +- GitHub: all toolsets +- Web-fetch +- Bash: enabled + +**Timeout:** 10 minutes + +**What it does:** + +1. **Responds to Queries:** + - Detects `/q` command in Issues or comments + - Understands natural language questions + - Searches repository for relevant information + - Provides helpful answers + +2. **Use Cases:** + - "What's the planting schedule for North Field?" + - "When was the last oil change for the tractor?" + - "Who is responsible for livestock health records?" + - "What grants are due this month?" + +3. **Provides Context:** + - Links to relevant files + - Cites specific lines or sections + - Offers related documentation + - Suggests next steps + +**Using Q:** + +In any Issue or comment, type: + +````markdown +/q When is the next vet visit scheduled? +```` + +Q will respond with: + +````markdown +Based on `livestock/veterinary-log.md`, the next scheduled vet visit is: + +**Date:** 2026-03-15 +**Purpose:** Spring vaccinations for cattle herd +**Veterinarian:** Dr. Sarah Johnson + +See [veterinary-log.md](../livestock/veterinary-log.md#line-42) for details. +```` + +**Customization:** + +Add farm-specific knowledge: + +````markdown +## Q Knowledge Base + +- Tractor mechanic: Mike's Repair, (555) 123-4567 +- Preferred vet: Dr. Johnson, (555) 234-5678 +- Seed supplier: County Farm Supply +- Parts vendor: AgriParts Direct +```` + +--- + +## Workflow Configuration Reference + +### Common Settings + +#### Network Access + +````yaml +network: defaults +```` + +Options: +- `defaults` - Standard GitHub Actions network +- `none` - No network access +- `full` - Unrestricted (not recommended) + +#### Timeout + +````yaml +timeout-minutes: 15 +```` + +Recommended timeouts: +- Simple checks: 5-10 minutes +- Quality assurance: 15-30 minutes +- Complex analysis: 30-60 minutes + +#### Tools Configuration + +````yaml +tools: + github: + toolsets: [all] # or [repos, issues, pull_requests, etc.] + web-fetch: + bash: true +```` + +Available GitHub toolsets: +- `repos` - Repository operations +- `issues` - Issue management +- `pull_requests` - PR operations +- `actions` - Workflow management +- `all` - Everything + +#### Safe Outputs + +````yaml +safe-outputs: + create-pull-request: + draft: true + labels: [automation, documentation] + create-issue: + labels: [automation, qa] +```` + +Available safe outputs: +- `create-pull-request` +- `create-issue` +- `create-issue-comment` +- `noop` (status message) + +--- + +## Workflow Labels + +All automated workflows apply these labels: + +| Label | Applied By | Purpose | +|-------|-----------|---------| +| `automation` | All workflows | Identifies automated creation | +| `documentation` | Update Docs | Documentation changes | +| `qa` | Daily QA | Quality assurance Issues | +| `ci` | CI Doctor | Workflow health Issues | +| `dependencies` | Dependabot | Dependency updates | + +--- + +## Troubleshooting Workflows + +### Workflow Won't Run + +**Check:** + +1. **Is it enabled?** + - Actions tab β†’ Select workflow β†’ Check if disabled + +2. **Are permissions correct?** + - Verify workflow file permissions block + - Check repository settings β†’ Actions β†’ General + +3. **Is trigger correct?** + - Verify trigger event matches expectations + - Check if conditions are met (e.g., specific branch) + +4. **Repository settings:** + - Actions tab β†’ Settings β†’ Allow all actions + +### Workflow Fails + +**Debugging steps:** + +1. **View logs:** + - Actions tab β†’ Failed run β†’ Click job β†’ Expand steps + +2. **Check error message:** + - Look for red X icons + - Read error output + - Note the failing step + +3. **Common fixes:** + + **Permission denied:** + ````yaml + permissions: + issues: write # Add missing permission + ```` + + **Timeout:** + ````yaml + timeout-minutes: 30 # Increase from 15 + ```` + + **Missing secret:** + - Settings β†’ Secrets and variables β†’ Actions β†’ New secret + +4. **Re-run workflow:** + - Actions tab β†’ Failed run β†’ Re-run jobs + +### Agentic Workflow Issues + +**Compilation errors:** + +````bash +# Validate markdown syntax +gh aw validate + +# Recompile all workflows +gh aw compile + +# Compile specific workflow +gh aw compile .github/workflows/update-docs.md +```` + +**Runtime issues:** + +1. Check `.lock.yml` file is up-to-date +2. Verify source reference is valid +3. Test with workflow_dispatch trigger +4. Review job logs for AI decisions + +--- + +## Modifying Workflows + +### Editing Standard Workflows + +1. Create a branch: `git checkout -b workflow/update-weekly-reminder` +2. Edit the `.yml` file +3. Test with workflow_dispatch +4. Create Pull Request +5. Review and merge + +### Editing Agentic Workflows + +1. Create a branch: `git checkout -b workflow/update-issue-triage` +2. Edit the `.md` file (NOT the `.lock.yml`) +3. Compile: `gh aw compile` +4. Commit both `.md` and updated `.lock.yml` +5. Test with workflow_dispatch +6. Create Pull Request +7. Review and merge + +**Important:** Always commit both the `.md` source and compiled `.lock.yml` file. + +--- + +## Workflow Best Practices + +### Do: + +βœ… **Test changes** with workflow_dispatch before merging +βœ… **Use descriptive names** for workflow files +βœ… **Set appropriate timeouts** to avoid hanging +βœ… **Include error handling** in custom scripts +βœ… **Document customizations** in comments +βœ… **Version control workflows** with pull requests + +### Don't: + +❌ **Edit `.lock.yml` directly** - Edit `.md` and recompile +❌ **Use overly broad permissions** - Grant minimum required +❌ **Skip testing** - Always test workflow changes +❌ **Hardcode secrets** - Use repository secrets +❌ **Set excessive timeouts** - Keep under 60 minutes +❌ **Ignore failed workflows** - Investigate and fix + +--- + +## Advanced Customization + +### Adding Custom Workflow + +1. **Choose type:** + - Standard for simple, scripted logic + - Agentic for context-aware, adaptive behavior + +2. **Create file:** + - `.github/workflows/my-workflow.yml` (standard) + - `.github/workflows/my-workflow.md` (agentic) + +3. **Define trigger and permissions** + +4. **Write job logic** + +5. **Test thoroughly** + +6. **Document in this reference** + +### Workflow Composition + +Combine multiple workflows for complex automation: + +````yaml +jobs: + call-qa: + uses: ./.github/workflows/daily-qa.md + + call-docs: + uses: ./.github/workflows/update-docs.md + needs: call-qa +```` + +--- + +## Security Considerations + +### Permissions + +Always use minimum required permissions: + +````yaml +permissions: + contents: read # Default: read-only + issues: write # Only if creating/updating Issues + pull-requests: write # Only if creating/updating PRs +```` + +### Secrets + +Never hardcode sensitive data: + +````yaml +# ❌ Wrong +env: + API_KEY: "abc123secret" + +# βœ… Correct +env: + API_KEY: ${{ secrets.API_KEY }} +```` + +### Third-party Actions + +Agentic workflows use trusted sources: + +````yaml +source: githubnext/agentics/workflows/update-docs.md@ +```` + +Always pin to specific commit hash, not branch. + +--- + +## Monitoring and Maintenance + +### Weekly Checks + +- Review Actions tab for failed workflows +- Check for CI Doctor Issues +- Verify scheduled workflows are running +- Review automated PRs and Issues + +### Monthly Maintenance + +- Update workflow dependencies +- Review and update schedules +- Assess automation effectiveness +- Update documentation +- Archive resolved automation Issues + +### Quarterly Reviews + +- Evaluate workflow performance +- Gather user feedback +- Identify improvement opportunities +- Update workflow configurations +- Train team on new features + +--- + +## Getting Help + +### Workflow Issues + +- Create Issue labeled `automation`, `question` +- Include workflow name and run ID +- Attach error logs +- Describe expected vs. actual behavior + +### Enhancement Requests + +- Start a Discussion +- Describe desired automation +- Explain use case +- Suggest implementation approach + +### Documentation + +- [GitHub Actions Documentation](https://docs.github.com/actions) +- [Workflow Syntax Reference](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) +- [Agentic Workflows Documentation](https://githubnext.com/projects/agentic-workflows) + +--- + +## Related Documentation + +- [Automation Overview](./automation-overview.md) - User-friendly automation guide +- [Getting Started](./getting-started.md) - Repository basics +- [Labels Guide](./labels-guide.md) - Label system reference