Conversation
- 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>
github-actions
bot
added
automation
documentation
zircote
deleted the
docs/add-workflow-and-automation-guides-69ab4432090979fc
branch
There was a problem hiding this comment.
Pull request overview
Adds a new docs/ documentation set and links it from the root README to help contributors understand labeling and automation/workflows in the Sunny Acres Farm repo.
Changes:
- Introduces new documentation pages under
docs/(getting started, labels guide, automation overview, workflow reference). - Adds a
docs/README.mdindex for the documentation set. - Updates the root
README.mdto link to the new docs.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 17 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/workflow-reference.md | New technical reference for standard + agentic workflows, including configuration/troubleshooting guidance. |
| docs/labels-guide.md | New guide explaining label categories and usage patterns. |
| docs/getting-started.md | New onboarding/tutorial doc describing repo structure and common contribution workflows. |
| docs/automation-overview.md | New explanation doc summarizing automated workflows and how to interact with them. |
| docs/README.md | New docs landing page / navigation index. |
| README.md | Adds “New to this repository?” section with links into docs/. |
| - 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 |
There was a problem hiding this comment.
The Issue Triage workflow details here don’t match the actual .github/workflows/issue-triage.md: it triggers on issues: [opened, reopened] (no workflow_dispatch), uses safe-outputs: add-labels/add-comment (not create-issue/create-issue-comment), toolsets are limited to [issues], and timeout-minutes is 10. Please update this section to reflect the real frontmatter so readers don’t misconfigure it.
| - 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 | |
| - issues: [opened, reopened] | |
| **Permissions:** read-all | |
| **Safe outputs:** | |
| - add-labels | |
| - add-comment | |
| - Labels: `automation` | |
| **Tools:** | |
| - GitHub: [issues] | |
| - Bash: enabled | |
| **Timeout:** 10 minutes |
| 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 | |
There was a problem hiding this comment.
This “All automated workflows apply these labels” table looks inaccurate for the repo: weekly-reminder.yml applies routine/maintenance (not automation) and Dependabot PRs are labeled by Dependabot, not by repository workflows. Please adjust the wording/table to reflect which workflows actually apply which labels in this repo.
| 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 | | |
| The following labels are applied automatically by specific workflows or GitHub services: | |
| | Label | Applied By | Purpose | | |
| |-------|-----------|---------| | |
| | `automation` | Update Docs, Daily QA, CI Doctor | Identifies issues and PRs created by automated workflows | | |
| | `documentation` | Update Docs | Documentation changes | | |
| | `qa` | Daily QA | Quality assurance Issues | | |
| | `ci` | CI Doctor | Workflow health Issues | | |
| | `dependencies` | Dependabot service | Dependency updates created by Dependabot | | |
| | `routine` | Weekly Farm Reminder | Marks standing weekly reminder Issues | | |
| | `maintenance` | Weekly Farm Reminder | Tracks recurring maintenance follow-up work | |
| | `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 | |
There was a problem hiding this comment.
The Status Labels list includes waiting-on-approval, but the repo’s label config defines needs-review instead. To avoid users applying non-existent labels, please update this section to match .github/labels.yml.
| | `waiting-on-approval` | 📋 Beige | Decision or authorization pending | | |
| | `needs-review` | 📋 Beige | Waiting for review or approval from someone else | |
|
|
||
| - [Getting Started Guide](./getting-started.md) - Repository basics | ||
| - [Automation Overview](./automation-overview.md) - Automated workflows | ||
| - [Labels Configuration](../.github/labels.yml) - Complete label definitions |
There was a problem hiding this comment.
The “Labels Configuration” link text says “Complete label definitions,” but .github/labels.yml currently only defines domain/type/priority/status (ending at needs-review). Please adjust the wording (or expand the config) so the reference isn’t misleading.
| - [Labels Configuration](../.github/labels.yml) - Complete label definitions | |
| - [Labels Configuration](../.github/labels.yml) - Configured label categories and colors |
| **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` | ||
|
|
There was a problem hiding this comment.
Daily QA is documented as running at 2:00 AM UTC and creating Issues, but the workflow config creates Discussions/PRs/comments and the compiled cron time differs (daily-qa.lock.yml uses a scattered cron). Please update the schedule and outputs in this section to match the actual workflow.
| | 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 | |
There was a problem hiding this comment.
The “Workflow Schedule” table hard-codes Daily QA at 2:00 AM UTC and CI Doctor as “when workflows fail,” which doesn’t match the compiled workflows (daily-qa.lock.yml has a scattered cron; ci-doctor.md monitors specific workflows only). Please update this table so it matches current workflow configuration.
| | 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 | | |
| | Daily QA | On a staggered cron schedule (see `.github/workflows/daily-qa.lock.yml`) | | |
| | Issue Triage | On new Issue creation | | |
| | Update Docs | On push to main branch | | |
| | CI Doctor | When monitored workflows fail (see `ci-doctor.md`) | |
| 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 |
There was a problem hiding this comment.
The “Available GitHub toolsets” list includes actions, but the MCP GitHub server in this repo is configured with GITHUB_TOOLSETS: context,repos,issues,pull_requests (see .github/workflows/ci-doctor.lock.yml). Please update this list so it matches what workflows can actually access.
| 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 | |
| toolsets: [context, repos, issues, pull_requests] # matches configured GITHUB_TOOLSETS | |
| web-fetch: | |
| bash: true |
Available GitHub toolsets:
context- Read-only context about the current repo and workflowrepos- Repository operationsissues- Issue managementpull_requests- PR operations
| - 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 |
There was a problem hiding this comment.
The Q workflow details (triggers/permissions/safe outputs/tools) don’t match .github/workflows/q.md, which is triggered via slash_command and supports create-pull-request + add-comment safe outputs, with bash/edit tools. Please update this section to mirror the workflow’s frontmatter so the reference stays technically accurate.
| - 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 | |
| - `slash_command`: `/q` | |
| **Permissions:** read-all | |
| **Safe outputs:** | |
| - `create-pull-request` | |
| - `add-comment` | |
| **Tools:** | |
| - `bash` | |
| - `edit` |
| | `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 | |
There was a problem hiding this comment.
The Type Labels list includes documentation, but .github/labels.yml does not define a documentation label and it does define field-observation (which isn’t listed here). Please sync this guide with the actual label configuration (or update .github/labels.yml if these labels are intended to exist).
| | `documentation` | 📘 Blue | Record updates, reports, documentation | | |
| | `field-observation` | 📘 Blue | Field checks, scouting notes, soil and crop observations | |
| ## 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 | | ||
|
|
There was a problem hiding this comment.
This “Special Purpose Labels” section documents labels like automation, qa, ci, and question, but none of these appear in .github/labels.yml. Either add them to the label configuration or clarify that they may not be present / are managed outside the repo file.
Overview
This PR adds comprehensive documentation to help users understand and work with the Sunny Acres Farm repository.
What's New
Documentation Structure
Created a new
docs/directory with structured documentation:Main README Updates
Updated the main README with links to the new documentation, making it easier for users to find help.
Documentation Highlights
Getting Started Guide
Labels Guide
Automation Overview
Workflow Reference
Documentation Framework
These docs follow the Diátaxis framework:
Style Guidelines
Documentation follows:
Benefits
This documentation helps users:
Testing
Related Issues
Addresses documentation gaps identified in repository analysis:
Next Steps
After merging:
This PR was created by the Update Docs workflow to ensure code changes are mirrored by clear, accurate documentation.