From aa729eba44a8f9c04eed4c5b8aa6b71795ed10e1 Mon Sep 17 00:00:00 2001 From: GitHub Copilot Workflows Date: Tue, 17 Feb 2026 02:53:54 +0000 Subject: [PATCH] docs: add comprehensive documentation hub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add DiΓ‘taxis-structured documentation with tutorials, how-to guides, reference materials, and explanations to improve repository usability. New documentation includes: - Documentation hub with clear navigation (docs/README.md) - Getting Started tutorial for new users - How-to guide for adding crop records - Farm glossary with 50+ terms - Complete data dictionary with field definitions - Label reference guide - File naming conventions - Seasonal calendar explaining farm operations - Explanation of why GitHub works for farm management Documentation follows: - DiΓ‘taxis framework (tutorials/how-to/reference/explanation) - Plain language principles - Progressive disclosure (high-level first) - Accessibility best practices Updated root README to link to new documentation hub. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 + docs/README.md | 86 ++++++ docs/explanation/seasonal-calendar.md | 371 ++++++++++++++++++++++++++ docs/explanation/why-github.md | 279 +++++++++++++++++++ docs/how-to/add-crop-record.md | 155 +++++++++++ docs/reference/data-dictionary.md | 253 ++++++++++++++++++ docs/reference/glossary.md | 176 ++++++++++++ docs/reference/labels.md | 291 ++++++++++++++++++++ docs/reference/naming-conventions.md | 286 ++++++++++++++++++++ docs/tutorials/getting-started.md | 124 +++++++++ 10 files changed, 2023 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/explanation/seasonal-calendar.md create mode 100644 docs/explanation/why-github.md create mode 100644 docs/how-to/add-crop-record.md create mode 100644 docs/reference/data-dictionary.md create mode 100644 docs/reference/glossary.md create mode 100644 docs/reference/labels.md create mode 100644 docs/reference/naming-conventions.md create mode 100644 docs/tutorials/getting-started.md diff --git a/README.md b/README.md index 1d30ed8..58aac90 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ 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 [Documentation Hub](./docs/) for tutorials, how-to guides, and reference materials. + --- ## Quick Links diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..41bff28 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,86 @@ +# Sunny Acres Farm Documentation + +Welcome to the comprehensive documentation for the Sunny Acres Farm repository. This documentation helps you understand and effectively use this repository to manage farm operations. + +## Documentation Structure + +This documentation follows the [DiΓ‘taxis](https://diataxis.fr/) framework, organizing content into four types: + +### πŸ“š [Tutorials](./tutorials/) +**Learning-oriented** β€” Step-by-step lessons for newcomers + +Start here if you're new to the repository. These guides walk you through your first tasks from start to finish. + +- [Getting Started](./tutorials/getting-started.md) +- [Your First Issue](./tutorials/creating-your-first-issue.md) +- [Recording Equipment Maintenance](./tutorials/recording-equipment-maintenance.md) + +### πŸ”§ [How-To Guides](./how-to/) +**Task-oriented** β€” Practical steps to accomplish specific goals + +Use these when you need to complete a specific task or solve a particular problem. + +- [Adding Crop Records](./how-to/add-crop-record.md) +- [Logging Equipment Maintenance](./how-to/log-equipment-maintenance.md) +- [Updating Livestock Health Records](./how-to/update-livestock-health.md) +- [Tracking Compliance Deadlines](./how-to/track-compliance-deadlines.md) +- [Using GitHub Issues Effectively](./how-to/use-github-issues.md) + +### πŸ“– [Reference](./reference/) +**Information-oriented** β€” Technical descriptions and specifications + +Consult these for precise details about data formats, fields, and terminology. + +- [Data Dictionary](./reference/data-dictionary.md) +- [Farm Glossary](./reference/glossary.md) +- [File Naming Conventions](./reference/naming-conventions.md) +- [Label Reference](./reference/labels.md) + +### πŸ’‘ [Explanation](./explanation/) +**Understanding-oriented** β€” Background, context, and design decisions + +Read these to understand the "why" behind farm operations and repository design. + +- [Farm Operations Overview](./explanation/farm-operations.md) +- [Seasonal Calendar](./explanation/seasonal-calendar.md) +- [Repository Design](./explanation/repository-design.md) +- [Why GitHub for Farm Management](./explanation/why-github.md) + +--- + +## Quick Navigation + +| I want to... | Go to... | +|--------------|----------| +| Learn how to use this repository | [Getting Started Tutorial](./tutorials/getting-started.md) | +| Complete a specific task | [How-To Guides](./how-to/) | +| Look up a term or data field | [Reference Section](./reference/) | +| Understand farm workflows | [Explanation Section](./explanation/) | +| See farm data | [Main Repository](../) | + +--- + +## Farm Sections + +The repository organizes farm records into four main sections: + +- **[crops/](../crops/)** β€” Planting schedules, crop records, and soil data +- **[livestock/](../livestock/)** β€” Health records, feeding schedules, and vet logs +- **[equipment/](../equipment/)** β€” Maintenance logs, safety inspections, and inventory +- **[compliance/](../compliance/)** β€” Grant tracking and certifications + +Each section has its own README with specific documentation. + +--- + +## Contributing to Documentation + +Found something unclear or missing? See our [Contributing Guide](../CONTRIBUTING.md) to suggest improvements. Documentation improvements follow the same pull request process as any other contribution. + +--- + +**About Sunny Acres Farm** + +This is a 320-acre diversified operation in the Midwest. We grow corn, soybeans, wheat, and alfalfa, and raise beef cattle, dairy cows, sheep, and horses. + +*This is a demo repository for GitHub training. All data is fictional.* diff --git a/docs/explanation/seasonal-calendar.md b/docs/explanation/seasonal-calendar.md new file mode 100644 index 0000000..85be730 --- /dev/null +++ b/docs/explanation/seasonal-calendar.md @@ -0,0 +1,371 @@ +# Seasonal Calendar + +Understanding the annual cycle of farm operations at Sunny Acres. + +## Overview + +Farm work follows natural seasonal patterns. This calendar helps you understand what happens when, and how different operations connect throughout the year. + +--- + +## Spring (March - May) + +**Theme:** Preparation and Planting + +### Early Spring (March) +**What's Happening:** +- Snow melts, fields begin to dry +- Equipment comes out of winter storage +- Soil testing begins + +**Key Activities:** +- Test soil in all fields +- Service and repair equipment +- Purchase seeds and supplies +- Plan crop rotations +- Monitor weather forecasts + +**Livestock:** +- Spring calving begins (beef cattle) +- Increase feeding as pregnant animals need more nutrition +- Prepare lambing pens +- Monitor for early births + +**Repository Activity:** +- Update planting schedules +- Log equipment maintenance +- Record soil test results +- Review grant compliance requirements + +### Mid-Spring (April) +**What's Happening:** +- Fields dry enough to enter +- First opportunity for field work +- Lambing season peaks + +**Key Activities:** +- Spread fertilizer based on soil tests +- Begin tillage (if using conventional methods) +- Plant early crops (spring wheat, oats) +- Calibrate planters + +**Livestock:** +- Peak lambing season (sheep) +- Dairy cows turned out to pasture as weather permits +- Horses begin light work in fields +- Monitor newborn calves + +**Repository Activity:** +- Document planting progress +- Track fertilizer applications +- Update livestock health records (births) +- Log equipment hours + +### Late Spring (May) +**What's Happening:** +- Prime planting window +- All hands on deck for fieldwork +- Risk of late frost diminishes + +**Key Activities:** +- Plant corn (early May) +- Plant soybeans (mid-May) +- Monitor seedling emergence +- Scout for pests and diseases + +**Livestock:** +- Turn cattle to pasture full-time +- Begin rotational grazing +- Spring vaccinations +- Wean lambs from ewes + +**Repository Activity:** +- Complete planting schedule updates +- Track actual vs. planned planting dates +- Document field conditions +- Log veterinary visits + +--- + +## Summer (June - August) + +**Theme:** Growth and Maintenance + +### Early Summer (June) +**What's Happening:** +- Crops growing rapidly +- First cutting of alfalfa +- Long days, intense work period + +**Key Activities:** +- Scout fields for weeds, pests, diseases +- Apply herbicides if needed +- First alfalfa harvest +- Cultivate between rows (if applicable) + +**Livestock:** +- Manage pasture rotation +- Monitor heat stress in animals +- Ensure adequate water supply +- Continue dairy operations + +**Repository Activity:** +- Document pest/disease observations +- Log herbicide applications +- Track hay harvest quantities +- Update equipment hours + +### Mid-Summer (July) +**What's Happening:** +- Peak growing season +- Wheat harvest begins +- Hot weather management critical + +**Key Activities:** +- Harvest winter wheat +- Second cutting of alfalfa +- Monitor crop development +- Manage irrigation (if applicable) + +**Livestock:** +- Monitor for heat stress +- Increase water availability +- Fly control measures +- Watch for summer diseases + +**Repository Activity:** +- Record wheat harvest yields +- Update storage inventory +- Log livestock health issues +- Document water/feed adjustments + +### Late Summer (August) +**What's Happening:** +- Corn and soybeans maturing +- Final alfalfa cuttings +- Begin harvest preparation + +**Key Activities:** +- Monitor crop maturity +- Service and prepare harvest equipment +- Arrange grain storage +- Scout fields for harvest timing + +**Livestock:** +- Wean spring calves +- Prepare for fall breeding season +- Maintain pasture quality +- Continue fly control + +**Repository Activity:** +- Update expected harvest dates +- Log equipment maintenance +- Record weaning dates +- Track livestock weight gains + +--- + +## Fall (September - November) + +**Theme:** Harvest and Preparation + +### Early Fall (September) +**What's Happening:** +- Harvest season begins +- Long days in the field +- Weather watching intensifies + +**Key Activities:** +- Begin corn and soybean harvest +- Plant winter wheat +- Sell or store harvested grain +- Monitor moisture levels + +**Livestock:** +- Begin fall breeding (cattle) +- Increase feeding as pasture quality declines +- Prepare for winter housing +- Fall vaccinations + +**Repository Activity:** +- Track harvest progress by field +- Record yields and quality +- Document grain sales +- Log breeding records + +### Mid-Fall (October) +**What's Happening:** +- Peak harvest season +- Race against weather +- Winter preparations begin + +**Key Activities:** +- Continue corn and soybean harvest +- Final field work for the season +- Begin equipment winterization +- Spread fall fertilizer + +**Livestock:** +- Pregnancy check bred cows +- Wean remaining calves +- Begin transition to winter feeding +- Prepare barns for winter + +**Repository Activity:** +- Complete harvest records +- Update equipment hours +- Log equipment repairs +- Record pregnancy check results + +### Late Fall (November) +**What's Happening:** +- Harvest wraps up +- Fields rest +- Winter preparation intensifies + +**Key Activities:** +- Final equipment cleaning and storage +- Complete field records +- Annual equipment inspections +- Plan next year's rotations + +**Livestock:** +- Full winter feeding begins +- Monitor body condition +- Prepare for winter calving (if applicable) +- Increase bedding in barns + +**Repository Activity:** +- Finalize harvest reports +- Complete equipment maintenance logs +- Update winter feeding schedules +- Plan next year's crop rotations + +--- + +## Winter (December - February) + +**Theme:** Rest, Maintenance, and Planning + +### Early Winter (December) +**What's Happening:** +- Fields covered with snow +- Focus shifts to livestock +- Planning for next year + +**Key Activities:** +- Equipment repairs and overhauls +- Attend farm conferences and training +- Review financial records +- Order seeds for spring + +**Livestock:** +- Full winter feeding routine +- Monitor for cold stress +- Maintain water access (ice management) +- Watch for calving (if winter calving) + +**Repository Activity:** +- Document year-end summaries +- Update grant compliance reports +- Plan equipment purchases +- Review and update procedures + +### Mid-Winter (January) +**What's Happening:** +- Coldest period +- Minimal field work +- Maintenance and planning peak + +**Key Activities:** +- Continue equipment maintenance +- Finalize next year's crop plan +- Purchase inputs (seed, fertilizer, chemicals) +- Prepare tax documents + +**Livestock:** +- Maintain feeding schedule +- Monitor closely for health issues +- Prepare for spring calving/lambing +- Service dairy equipment + +**Repository Activity:** +- Update compliance certifications +- Renew licenses and permits +- Log equipment repairs +- Document winter livestock health + +### Late Winter (February) +**What's Happening:** +- Days lengthening +- Anticipation builds +- Final preparations for spring + +**Key Activities:** +- Final equipment checks +- Soil sampling preparation +- Review planting plan +- Check seed inventory + +**Livestock:** +- Monitor pregnant animals closely +- Prepare calving/lambing areas +- Begin spring vaccination planning +- Increase feeding for late-pregnancy animals + +**Repository Activity:** +- Update planting schedules +- Review previous year's data +- Plan veterinary visits +- Prepare for spring activities + +--- + +## Seasonal Patterns + +### Weather Windows +**Critical periods when weather dictates work:** +- **Spring planting window:** May 1-25 (narrow window for optimal planting) +- **Wheat harvest window:** July 10-25 (must harvest before rain spoils grain) +- **Fall harvest window:** September 15 - November 15 (race against frost and snow) + +### Equipment Use Cycles +- **Heavy use:** April-May (planting), September-October (harvest) +- **Moderate use:** June-August (maintenance, hay harvest) +- **Light use:** November-March (minimal field operations) + +### Livestock Cycles +- **Breeding:** September-November (cattle), November-December (sheep) +- **Birthing:** February-April (cattle), March-April (sheep) +- **Weaning:** August-October (cattle), April-May (sheep) + +--- + +## Using This Calendar + +**For planning:** +- Anticipate upcoming tasks +- Schedule equipment maintenance during low-use periods +- Coordinate multiple operations + +**For understanding:** +- See how crops, livestock, and equipment work together +- Understand why certain tasks happen at specific times +- Learn the rhythm of farm operations + +**For documentation:** +- Know what records to update when +- Understand context for historical data +- Plan ahead for reporting deadlines + +--- + +## Related Resources + +- [Farm Operations Overview](./farm-operations.md) β€” Deeper dive into each operation type +- [Getting Started Tutorial](../tutorials/getting-started.md) β€” Learn to use this repository +- [How-To Guides](../how-to/) β€” Specific task instructions + +--- + +*Seasonal patterns vary with weather and market conditions. This calendar represents typical operations at Sunny Acres Farm.* diff --git a/docs/explanation/why-github.md b/docs/explanation/why-github.md new file mode 100644 index 0000000..a9f47ee --- /dev/null +++ b/docs/explanation/why-github.md @@ -0,0 +1,279 @@ +# Why GitHub for Farm Management + +Understanding the reasoning behind using GitHub as a farm management system. + +## The Problem + +Traditional farm record-keeping faces several challenges: + +### 1. Scattered Information +- Paper records in filing cabinets +- Spreadsheets on multiple computers +- Notes on phones or tablets +- Memory-based systems + +**Result:** Hard to find information when needed, duplicate records, lost data. + +### 2. No Version History +- Can't see what changed and when +- Can't undo mistakes +- No audit trail for compliance +- Difficult to track trends over time + +**Result:** Uncertainty about past decisions, compliance risks, lost institutional knowledge. + +### 3. Collaboration Difficulties +- Multiple people can't edit simultaneously +- No clear ownership of tasks +- Hard to delegate or track completion +- Communication happens separately from data + +**Result:** Duplicated work, miscommunication, unclear responsibilities. + +### 4. Accessibility Issues +- Records locked on one computer +- Not accessible in the field +- Can't work offline +- Difficult to share with advisors or agencies + +**Result:** Delayed decisions, inefficiency, frustration. + +--- + +## The GitHub Solution + +GitHub solves these problems by providing: + +### 1. Centralized, Searchable Storage + +**All farm records in one place:** +- Crops, livestock, equipment, compliance +- Accessible from anywhere with internet +- Powerful search across all documents +- Organized, logical structure + +**Example:** +Need to know when you last serviced the tractor? Search for "John Deere service" and find all maintenance records instantly. + +### 2. Complete Version History + +**Every change is tracked:** +- Who changed what, when +- Ability to see previous versions +- Can revert mistakes +- Complete audit trail + +**Example:** +"I remember we planted earlier last year, but when exactly?" Check the commit history of planting-schedule.md to see last year's dates. + +### 3. Built-in Collaboration Tools + +**Work together effectively:** +- Issues for tasks and discussions +- Pull requests for reviewing changes +- Comments and feedback inline +- Automatic notifications + +**Example:** +Create an issue for "Oil change needed on tractor," assign it to a farmhand, track when it's completed. + +### 4. Free and Reliable + +**No subscription fees:** +- Free for public repositories +- Free for private repositories (with limits) +- Reliable infrastructure (99.9%+ uptime) +- Regular backups automatically + +### 5. Plain Text = Future-Proof + +**Data is always accessible:** +- Markdown files readable in any text editor +- Not locked to proprietary software +- Can migrate to other systems if needed +- Human-readable format + +**Example:** +In 20 years, you can still open these .md files in Notepad. Try that with a proprietary database format from 2005. + +--- + +## Common Objections Answered + +### "GitHub is for programmers, not farmers" + +**Response:** GitHub is a tool for managing any text-based information: +- No programming required for basic use +- Web interface is user-friendly +- Markdown is simpler than Word +- Many non-technical organizations use GitHub (museums, governments, researchers) + +**Farm-friendly features:** +- Point and click file editing +- Templates for common tasks +- Visual diff showing what changed +- Mobile-friendly web interface + +### "We need software specifically designed for farms" + +**Response:** Generic tools are often more powerful and flexible: +- Adapt to your specific needs, not vendor assumptions +- No forced upgrade cycles or subscription traps +- Combine with other tools as needed +- Community support from millions of users + +**Farm management software often:** +- Costs hundreds per year +- Locks you into one vendor +- May discontinue or change dramatically +- Doesn't integrate well with other tools + +### "Our internet is unreliable" + +**Response:** GitHub works offline with local git tools: +- Clone repository to your computer +- Work offline, sync later +- All data is local and remote +- Even the web interface caches well + +**Practical approach:** +- Use web interface when internet is good +- Use GitHub Desktop for offline work +- Sync when convenient + +### "What if GitHub goes away?" + +**Response:** Your data is always yours: +- Clone creates complete local copy +- Export to other Git services easily (GitLab, Bitbucket) +- Raw files are portable Markdown +- No vendor lock-in + +### "We don't have time to learn new technology" + +**Response:** Investment pays off quickly: +- Basic tasks learned in 30 minutes +- Time saved finding information +- Reduced duplicate work +- Better compliance documentation + +**Learning curve:** +- Day 1: Read files, create issues +- Week 1: Edit files, basic pull requests +- Month 1: Comfortable with full workflow +- Year 1: Wondering how you managed before + +--- + +## Real-World Advantages + +### Compliance and Audits +**Problem:** Inspector asks for proof of vaccination schedule from 3 years ago. + +**GitHub solution:** +1. Search for "vaccination 2023" +2. Find livestock/health-records.md from that time +3. View version history to show it was documented in real-time +4. Export to PDF or print + +**Result:** 5-minute task instead of hours searching paper files. + +### Trend Analysis +**Problem:** "What's our average corn yield over the last 5 years?" + +**GitHub solution:** +1. View commit history of crops/planting-schedule.md +2. Browse each year's harvest data +3. Compare year-to-year in the same document + +**Result:** Quick data analysis without maintaining separate spreadsheets. + +### Knowledge Transfer +**Problem:** Experienced farmhand retires, new person starts. + +**GitHub solution:** +- Complete history of all operations +- Comments and discussions provide context +- Templates show "how we do things here" +- New person can read back through years of decisions + +**Result:** Reduced learning curve, preserved institutional knowledge. + +### Team Coordination +**Problem:** Multiple people need to know what maintenance is due. + +**GitHub solution:** +1. Create issues for each maintenance task +2. Assign to responsible person +3. Everyone can see what's pending +4. Automated reminders via email +5. Check off when complete + +**Result:** Clear responsibilities, nothing falls through cracks. + +### Professional Presentation +**Problem:** Need to provide farm data to lender or grant agency. + +**GitHub solution:** +- Clean, professional presentation +- Shows organized, modern operation +- Demonstrates commitment to record-keeping +- Easy to share specific records + +**Result:** Improved credibility with financial and regulatory stakeholders. + +--- + +## What GitHub Doesn't Do Well + +**Be realistic about limitations:** + +### Not Ideal For: +- **Large binary files** (photos, videos, CAD files) β€” use cloud storage instead +- **Real-time data entry** β€” mobile apps may be better for in-field work +- **Complex calculations** β€” use spreadsheets or specialized tools +- **Non-text data** β€” databases may be better for highly structured data + +### Best Used Alongside: +- Cloud storage (Google Drive, Dropbox) for photos/documents +- Spreadsheets (Excel, Google Sheets) for financial analysis +- Mobile apps for quick field notes +- Specialized tools (QuickBooks for accounting) + +--- + +## The Bottom Line + +**GitHub provides:** +- βœ… Free, reliable infrastructure +- βœ… Complete version control +- βœ… Excellent collaboration tools +- βœ… Portable, future-proof data +- βœ… Powerful search and organization +- βœ… No vendor lock-in + +**In exchange for:** +- ❌ Small learning curve +- ❌ Text-based (not visual) +- ❌ Internet-dependent for web interface +- ❌ Not farm-specific features + +**Verdict:** For text-based farm records, GitHub offers unmatched value, flexibility, and longevity. + +--- + +## Getting Started + +Ready to give it a try? Start with: + +1. [Getting Started Tutorial](../tutorials/getting-started.md) +2. [Creating Your First Issue](../tutorials/creating-your-first-issue.md) +3. [How to Add a Crop Record](../how-to/add-crop-record.md) + +Still have questions? Open an issue with the **question** label. + +--- + +**See also:** +- [Repository Design](./repository-design.md) β€” How this repository is organized +- [Farm Operations Overview](./farm-operations.md) β€” What we track and why diff --git a/docs/how-to/add-crop-record.md b/docs/how-to/add-crop-record.md new file mode 100644 index 0000000..f4ad8bd --- /dev/null +++ b/docs/how-to/add-crop-record.md @@ -0,0 +1,155 @@ +# How to Add a Crop Record + +**Task:** Document a new crop planting or harvest event +**Time:** 5 minutes +**Prerequisites:** Repository access, basic GitHub knowledge + +## When to Use This Guide + +Use this guide when you need to: + +- Record new planting dates +- Update crop rotation plans +- Document harvest information +- Add soil test results + +## Steps + +### 1. Determine Which File to Update + +Navigate to the **crops/** directory and choose the appropriate file: + +- **planting-schedule.md** β€” For recording planting dates +- **crop-rotation-plan.md** β€” For updating rotation strategy +- **soil-test-results.md** β€” For adding new soil analysis +- **README.md** β€” For updating current season status + +### 2. Create a Branch + +You cannot edit the main branch directly. Create a branch for your changes: + +1. Navigate to the file you want to edit +2. Click the **pencil icon** (Edit this file) +3. GitHub will automatically create a branch, or you can name it yourself: + - Use format: `crops/update-planting-schedule-YYYY-MM-DD` + - Example: `crops/update-planting-schedule-2026-02-17` + +### 3. Edit the File + +**Example: Adding a planting record to planting-schedule.md** + +Find the table for the relevant field and add a new row: + +````markdown +| Field | Crop | Variety | Planting Date | Expected Harvest | +|-------|------|---------|---------------|------------------| +| North 40 | Corn | Pioneer P1197 | 2026-05-01 | 2026-10-15 | +| South Field | Soybeans | Asgrow AG24X9 | 2026-05-15 | 2026-10-20 | +| East Section | Wheat | WB-Grainfield | 2026-09-20 | 2027-07-10 | +| **West Field** | **Corn** | **DeKalb DKC62-54** | **2026-05-05** | **2026-10-18** | +```` + +**Format requirements:** + +- Keep table alignment consistent (use pipes `|`) +- Use ISO date format (YYYY-MM-DD) +- Include all required columns +- Be specific about varieties when known + +### 4. Write a Commit Message + +At the bottom of the edit page, write a clear commit message: + +**Good examples:** +- "Add corn planting date for West Field" +- "Update harvest dates for North 40 corn crop" +- "Add 2026 soil test results for South Field" + +**Poor examples:** +- "Update" (too vague) +- "Fixed stuff" (unclear what changed) +- "asdfjkl" (meaningless) + +### 5. Create a Pull Request + +1. Click **Propose changes** (or **Commit changes**) +2. On the next page, click **Create pull request** +3. Fill in the PR template: + - **Title:** Same as your commit message (or more descriptive) + - **Description:** Explain what changed and why + - Example: "Added planting date for West Field corn crop. Planting scheduled for May 5, 2026 using DeKalb DKC62-54 variety." +4. Add labels if appropriate: + - **crops** (automatically added) + - **planning** or **documentation** +5. Click **Create pull request** + +### 6. Request Review (Optional) + +If your farm has designated reviewers: + +1. Click the gear icon next to **Reviewers** on the right sidebar +2. Select the appropriate reviewer +3. They'll be notified to review your changes + +### 7. Merge the Pull Request + +Once approved (or if no review is required): + +1. Click **Merge pull request** +2. Confirm the merge +3. Delete the branch (GitHub will prompt you) + +Your crop record is now updated! + +## Special Cases + +### Adding a New Field + +If you're documenting a new field that doesn't exist in the schedule: + +1. Follow steps 1-3 above +2. Add a new row at the appropriate location (alphabetically or by field layout) +3. Update the crops/README.md if needed to mention the new field + +### Updating Historical Data + +If correcting past records: + +1. Make the edit clearly +2. In your commit message, note it's a correction: "Correct planting date for North 40 (was May 10, should be May 12)" +3. Consider adding a note in the description explaining the correction + +### Bulk Updates + +If updating multiple entries: + +1. Make all changes in a single commit +2. List each change in your commit message: + ``` + Update multiple crop records: + - Add North 40 planting date + - Update South Field harvest date + - Correct West Field variety name + ``` + +## Troubleshooting + +**Problem:** "You don't have permission to edit this file" +**Solution:** You may not have write access. Contact the repository administrator. + +**Problem:** "Merge conflict detected" +**Solution:** Someone else edited the same lines. You'll need to resolve the conflict manually or ask for help. + +**Problem:** "Table formatting looks broken" +**Solution:** Ensure each row has the same number of pipes (`|`) as the header row. + +## Related Guides + +- [Track Compliance Deadlines](./track-compliance-deadlines.md) β€” Link crop activities to compliance requirements +- [Use GitHub Issues Effectively](./use-github-issues.md) β€” Create issues for planting tasks + +## Need Help? + +- Open an issue with the **question** label +- Check [Getting Started Tutorial](../tutorials/getting-started.md) +- Review [File Naming Conventions](../reference/naming-conventions.md) diff --git a/docs/reference/data-dictionary.md b/docs/reference/data-dictionary.md new file mode 100644 index 0000000..c94cdb8 --- /dev/null +++ b/docs/reference/data-dictionary.md @@ -0,0 +1,253 @@ +# Data Dictionary + +Technical reference for data fields used throughout the Sunny Acres farm repository. + +## Overview + +This document defines the structure, format, and validation rules for all data fields used in farm records. + +## Standard Data Types + +### Date Fields +- **Format:** ISO 8601 (YYYY-MM-DD) +- **Examples:** 2026-02-17, 2026-05-01, 2026-12-31 +- **Validation:** Must be valid calendar date +- **Usage:** All date fields (planting dates, service dates, deadlines) + +### Numeric Fields +- **Whole numbers:** No decimal point (e.g., 45, 320, 12) +- **Decimal numbers:** Use decimal point, 1-2 decimal places (e.g., 5.5, 123.75) +- **Currency:** USD format with 2 decimal places (e.g., $1,234.56) + +### Text Fields +- **Short text:** Single line, max 100 characters +- **Long text:** Multi-line, max 1000 characters +- **Restricted text:** Must match specific values (see field definitions below) + +## Crop Data Fields + +### Planting Schedule (crops/planting-schedule.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Field | Short text | Yes | Field name from approved list | "North 40" | +| Crop | Short text | Yes | Crop type | "Corn", "Soybeans", "Wheat" | +| Variety | Short text | No | Specific cultivar/hybrid | "Pioneer P1197" | +| Planting Date | Date | Yes | YYYY-MM-DD | "2026-05-01" | +| Expected Harvest | Date | No | YYYY-MM-DD | "2026-10-15" | +| Acres | Decimal | No | Numeric, 1 decimal | "40.0" | +| Notes | Long text | No | Additional details | "Weather delayed" | + +**Approved Field Names:** +- North 40 +- South Field +- East Section +- West Field +- Home Pasture +- Back Pasture + +**Approved Crop Types:** +- Corn +- Soybeans +- Wheat (Winter Wheat, Spring Wheat) +- Alfalfa +- Hay + +### Crop Rotation Plan (crops/crop-rotation-plan.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Year | Numeric | Yes | YYYY | "2026" | +| Field | Short text | Yes | Field name | "North 40" | +| Planned Crop | Short text | Yes | Crop type | "Corn" | +| Previous Crop | Short text | No | Crop type | "Soybeans" | +| Rationale | Long text | No | Explanation | "Nitrogen fixation from previous soybeans" | + +### Soil Test Results (crops/soil-test-results.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Field | Short text | Yes | Field name | "North 40" | +| Sample Date | Date | Yes | YYYY-MM-DD | "2026-03-15" | +| Lab | Short text | Yes | Testing lab name | "AgSource Laboratories" | +| pH | Decimal | Yes | 0.0-14.0, 1 decimal | "6.5" | +| Organic Matter % | Decimal | No | 0.0-100.0, 1 decimal | "3.8" | +| Nitrogen (ppm) | Numeric | No | Parts per million | "25" | +| Phosphorus (ppm) | Numeric | No | Parts per million | "45" | +| Potassium (ppm) | Numeric | No | Parts per million | "180" | +| Recommendations | Long text | No | Lab recommendations | "Apply 150 lbs/acre nitrogen" | + +## Livestock Data Fields + +### Health Records (livestock/health-records.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Animal ID | Short text | Yes | Unique identifier | "BC-045", "DC-03", "SH-12" | +| Animal Type | Short text | Yes | Species | "Beef Cattle", "Dairy Cow", "Sheep", "Horse" | +| Date | Date | Yes | YYYY-MM-DD | "2026-02-10" | +| Event Type | Short text | Yes | Health event category | "Vaccination", "Treatment", "Checkup" | +| Description | Long text | Yes | Details of event | "Annual vaccination - IBR, BVD, PI3" | +| Veterinarian | Short text | No | Vet name | "Dr. Sarah Johnson" | +| Cost | Currency | No | USD | "$125.00" | +| Next Due | Date | No | YYYY-MM-DD | "2027-02-10" | + +**Animal ID Format:** +- Beef Cattle: BC-### (e.g., BC-001, BC-045) +- Dairy Cows: DC-## (e.g., DC-01, DC-12) +- Sheep: SH-## (e.g., SH-01, SH-28) +- Horses: H-# (e.g., H-1, H-2, H-3) + +**Approved Event Types:** +- Vaccination +- Treatment +- Checkup +- Surgery +- Birth +- Weaning +- Observation + +### Feeding Schedule (livestock/feeding-schedule.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Animal Group | Short text | Yes | Group designation | "Beef Cattle", "Dairy Herd" | +| Feed Time | Short text | Yes | Time of day | "6:00 AM", "2:00 PM" | +| Feed Type | Short text | Yes | Feed description | "Hay", "Grain Mix", "Silage" | +| Amount | Short text | Yes | Quantity | "50 lbs", "2 bales" | +| Frequency | Short text | Yes | How often | "Daily", "Twice daily" | +| Notes | Long text | No | Additional info | "Increase by 10% in winter" | + +## Equipment Data Fields + +### Maintenance Log (equipment/maintenance-log.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Equipment Name | Short text | Yes | Full equipment name | "John Deere 6120M Tractor" | +| Date | Date | Yes | YYYY-MM-DD | "2026-02-01" | +| Service Type | Short text | Yes | Maintenance category | "Oil Change", "Inspection", "Repair" | +| Hours | Numeric | No | Hour meter reading | "1250" | +| Description | Long text | Yes | Work performed | "50-hour service, oil and filter change" | +| Performed By | Short text | No | Person/company | "John's Equipment Service" | +| Cost | Currency | No | USD | "$285.50" | +| Next Service Due | Date or Numeric | No | Date or hours | "2026-04-01" or "1450" | + +**Approved Service Types:** +- Oil Change +- Inspection +- Repair +- Tire Service +- Filter Replacement +- Calibration +- Annual Service + +### Inventory (equipment/inventory.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Equipment Name | Short text | Yes | Full equipment name | "Case IH 7150 Combine" | +| Category | Short text | Yes | Equipment type | "Tractor", "Implement", "Tool" | +| Year | Numeric | Yes | YYYY | "2017" | +| Make | Short text | Yes | Manufacturer | "Case IH" | +| Model | Short text | Yes | Model designation | "7150" | +| Serial Number | Short text | No | Manufacturer S/N | "JJA0123456" | +| Current Hours | Numeric | No | Hour meter reading | "2450" | +| Status | Short text | Yes | Operational status | "Operational", "Repair Needed", "Winterized" | +| Location | Short text | No | Storage location | "Main Barn", "North Shed" | + +**Approved Equipment Categories:** +- Tractor +- Combine +- Implement (Plow, Disc, Planter, etc.) +- Irrigation +- Tool +- Vehicle +- Attachment + +**Approved Status Values:** +- Operational +- Repair Needed +- Under Repair +- Winterized +- Retired + +## Compliance Data Fields + +### Grant Tracker (compliance/grant-tracker.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Grant Name | Short text | Yes | Program name | "EQIP Conservation" | +| Agency | Short text | Yes | Funding agency | "USDA NRCS" | +| Status | Short text | Yes | Current status | "Active", "Pending", "Completed" | +| Start Date | Date | No | YYYY-MM-DD | "2025-01-01" | +| End Date | Date | No | YYYY-MM-DD | "2027-12-31" | +| Award Amount | Currency | No | USD | "$15,000.00" | +| Reporting Deadline | Date | No | YYYY-MM-DD | "2026-06-30" | +| Contact | Short text | No | Agency contact | "Mike Thompson, Conservation Planner" | + +**Approved Status Values:** +- Active +- Pending +- Application Submitted +- Completed +- Denied +- Withdrawn + +### Certifications (compliance/certifications.md) + +| Field Name | Type | Required | Format | Example | +|------------|------|----------|--------|---------| +| Certification Name | Short text | Yes | Cert/license type | "Organic Certification" | +| Issuing Agency | Short text | Yes | Agency name | "State Ag Department" | +| Number | Short text | No | Cert/license number | "ORG-2024-12345" | +| Issue Date | Date | Yes | YYYY-MM-DD | "2024-01-15" | +| Expiration Date | Date | Yes | YYYY-MM-DD | "2027-01-14" | +| Status | Short text | Yes | Current status | "Active", "Pending Renewal" | +| Renewal Deadline | Date | No | YYYY-MM-DD | "2026-11-15" | +| Cost | Currency | No | USD | "$500.00" | + +**Approved Status Values:** +- Active +- Pending +- Pending Renewal +- Expired +- Suspended +- Application Submitted + +--- + +## Validation Rules + +### Required vs. Optional Fields +- **Required:** Must have a value, cannot be empty +- **Optional:** May be left empty if information is not available + +### Date Validation +All dates must: +- Use ISO 8601 format (YYYY-MM-DD) +- Represent valid calendar dates +- Be consistent (e.g., harvest date after planting date) + +### Text Length Limits +- Short text: 100 characters maximum +- Long text: 1000 characters maximum +- Exceed limits only when absolutely necessary + +### Numeric Validation +- Must be valid numbers +- No non-numeric characters (except decimal point or currency symbol) +- Negative numbers only where logically appropriate + +--- + +## Need Help? + +- Questions about field formats: See [Glossary](./glossary.md) +- Unsure what value to use: Open an issue with the **question** label +- Propose new fields: Create a pull request with documentation updates + +**See also:** +- [File Naming Conventions](./naming-conventions.md) +- [Getting Started Tutorial](../tutorials/getting-started.md) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md new file mode 100644 index 0000000..e213511 --- /dev/null +++ b/docs/reference/glossary.md @@ -0,0 +1,176 @@ +# Farm Glossary + +A comprehensive glossary of terms used in farm operations and this repository. + +## General Farm Terms + +### Acre +A unit of land measurement equal to 43,560 square feet. Sunny Acres operates 320 acres. + +### Crop Rotation +The practice of growing different types of crops in the same area across seasons to improve soil health and reduce pests. + +### Growing Season +The period of the year when crops can be grown, typically from last spring frost to first fall frost. + +### Harvest +The process of gathering mature crops from the fields. + +### Tillage +The agricultural preparation of soil by mechanical agitation (plowing, digging, stirring). + +## Crop Terms + +### Bushel +A unit of measurement for grain: +- Corn: 56 pounds per bushel +- Soybeans: 60 pounds per bushel +- Wheat: 60 pounds per bushel + +### Cultivar / Variety +A plant variety that has been produced in cultivation by selective breeding. Examples: Pioneer P1197 (corn), Asgrow AG24X9 (soybeans). + +### GMO (Genetically Modified Organism) +Crops whose genetic material has been altered using genetic engineering techniques. + +### Hybrid +A crop variety created by cross-pollinating two different parent varieties. + +### No-Till +A farming practice where crops are planted without plowing, leaving crop residue on the field. + +### Row Crop +Crops planted in rows wide enough to allow cultivation between rows. Examples: corn, soybeans. + +### Seed Treatment +Chemical or biological agents applied to seeds before planting to protect against diseases and pests. + +### Yield +The amount of crop harvested per acre, typically measured in bushels per acre. + +## Livestock Terms + +### Calving +The process of a cow giving birth to a calf. + +### Colostrum +The first milk produced by mammals after giving birth, rich in antibodies. + +### Culling +The process of removing animals from a herd due to age, health, or productivity issues. + +### Dry Cow +A dairy cow that is not currently being milked, typically in the last 60 days before calving. + +### Farrowing +The process of a sow (female pig) giving birth to piglets. + +### Heifer +A young female cow that has not yet given birth. + +### Lambing +The process of a ewe (female sheep) giving birth to lambs. + +### Weaning +The process of transitioning young animals from mother's milk to solid food. + +## Equipment Terms + +### Combine +A machine that harvests grain crops by combining three operations: reaping, threshing, and winnowing. + +### Hour Meter +A device that tracks how many hours a piece of equipment has operated, used for scheduling maintenance. + +### Implement +An attachment or tool used with a tractor (e.g., plow, disc, planter). + +### PTO (Power Take-Off) +A mechanism on a tractor that transfers power to attached implements. + +### Service Interval +The recommended time or usage period between maintenance tasks (e.g., oil change every 200 hours). + +### Tractor +A multi-purpose farm vehicle used to pull implements and perform various tasks. + +## Compliance & Regulatory Terms + +### CRP (Conservation Reserve Program) +A USDA program that pays farmers to remove environmentally sensitive land from production. + +### EQIP (Environmental Quality Incentives Program) +A USDA program providing financial assistance to implement conservation practices. + +### FSA (Farm Service Agency) +A USDA agency that administers farm support programs. + +### GAP (Good Agricultural Practices) +Food safety standards for produce production. + +### NRCS (Natural Resources Conservation Service) +A USDA agency providing technical assistance for conservation. + +### Organic Certification +Certification that farm products meet USDA organic standards. + +## Repository-Specific Terms + +### Issue +A GitHub feature used to track tasks, bugs, or questions. We use issues for farm tasks and maintenance tracking. + +### Label +A categorization tag applied to issues and pull requests (e.g., "crops", "urgent", "maintenance"). + +### Markdown (.md) +A lightweight markup language used for formatting text. All farm records are stored in Markdown files. + +### Pull Request (PR) +A GitHub feature for proposing changes to files. Required workflow for updating farm records. + +### Repository (Repo) +A storage location for project files and their revision history. This GitHub repository stores all Sunny Acres farm records. + +## Geographic Terms (Farm-Specific) + +### East Section +A 60-acre section on the eastern boundary, typically planted with wheat or alfalfa. + +### North 40 +A 40-acre field in the northern portion of the farm, primary corn field. + +### South Field +An 80-acre field in the southern portion, rotated between corn and soybeans. + +### West Field +A 50-acre field on the western boundary, secondary corn field. + +### Home Pasture +A 15-acre pasture near the farmhouse, used for horses and dairy cows. + +### Back Pasture +A 30-acre pasture in the rear of the property, used for beef cattle rotation. + +## Acronyms Quick Reference + +| Acronym | Full Term | +|---------|-----------| +| CRP | Conservation Reserve Program | +| EQIP | Environmental Quality Incentives Program | +| FSA | Farm Service Agency | +| GAP | Good Agricultural Practices | +| GMO | Genetically Modified Organism | +| NRCS | Natural Resources Conservation Service | +| PR | Pull Request | +| PTO | Power Take-Off | +| USDA | United States Department of Agriculture | + +--- + +## Contributing + +Found a term that should be added? See [CONTRIBUTING.md](../../CONTRIBUTING.md) to suggest additions. + +**See also:** +- [Data Dictionary](./data-dictionary.md) β€” Field definitions and data formats +- [Label Reference](./labels.md) β€” GitHub label meanings diff --git a/docs/reference/labels.md b/docs/reference/labels.md new file mode 100644 index 0000000..4b72dc2 --- /dev/null +++ b/docs/reference/labels.md @@ -0,0 +1,291 @@ +# Label Reference + +Complete guide to GitHub labels used in the Sunny Acres Farm repository. + +## Overview + +Labels are colored tags that categorize issues and pull requests. They help organize work, prioritize tasks, and filter information. + +## How to Use Labels + +### Viewing Issues by Label +1. Go to the **Issues** tab +2. Click any label to see all issues with that label +3. Or click **Labels** to see all available labels + +### Adding Labels +1. Open an issue or pull request +2. Look for **Labels** in the right sidebar +3. Click the gear icon +4. Select appropriate labels + +**Pro tip:** Most labels are automatically applied by issue templates. + +--- + +## Label Categories + +### Domain Labels +**What part of the farm is this about?** + +#### 🌾 crops +- **Color:** Green (#0E8A16) +- **Use for:** Crop planting, harvest, soil tests, field work +- **Examples:** + - "Update planting schedule for North 40" + - "Soil test results for South Field" + - "Corn harvest progress" + +#### πŸ„ livestock +- **Color:** Brown (#CD7F32) +- **Use for:** Animal health, feeding, breeding, veterinary care +- **Examples:** + - "Vaccination due for beef cattle" + - "Calf birth in North pasture" + - "Update feeding schedule for winter" + +#### 🚜 equipment +- **Color:** Blue (#0052CC) +- **Use for:** Machinery maintenance, repairs, purchases, safety +- **Examples:** + - "Oil change for John Deere tractor" + - "Combine needs tire repair" + - "Annual safety inspection due" + +#### πŸ“‹ compliance +- **Color:** Purple (#5319E7) +- **Use for:** Grants, certifications, regulations, reporting +- **Examples:** + - "EQIP report due June 30" + - "Renew organic certification" + - "Grant application for new irrigation" + +--- + +### Type Labels +**What kind of task is this?** + +#### πŸ”§ maintenance +- **Color:** Dark Blue (#1D76DB) +- **Use for:** Routine service, preventive care, scheduled tasks +- **Examples:** + - "500-hour service on tractor" + - "Clean and calibrate planter" + - "Quarterly fence inspection" + +#### πŸ› οΈ repair +- **Color:** Red (#B60205) +- **Use for:** Fixing broken equipment, addressing problems +- **Examples:** + - "Hydraulic leak on combine" + - "Replace broken fence post" + - "Fix barn door latch" + +#### πŸ“ planning +- **Color:** Light Blue (#BFD4F2) +- **Use for:** Future planning, strategy, decision-making +- **Examples:** + - "Plan 2027 crop rotation" + - "Decide on fall fertilizer application" + - "Budget for equipment purchases" + +#### πŸ‘οΈ inspection +- **Color:** Orange (#D93F0B) +- **Use for:** Safety checks, quality reviews, assessments +- **Examples:** + - "Annual equipment safety inspection" + - "Fence line inspection" + - "Grain storage quality check" + +#### πŸ’Š health +- **Color:** Pink (#E99695) +- **Use for:** Animal health, veterinary care, wellness +- **Examples:** + - "Cow limping in south pasture" + - "Schedule annual sheep vaccinations" + - "Monitor sick calf" + +--- + +### Priority Labels +**How urgent is this?** + +#### 🚨 urgent +- **Color:** Bright Red (#D93F0B) +- **Use for:** Immediate action required, safety issues, emergencies +- **Examples:** + - "Fence down, cattle at risk" + - "Equipment broken during harvest" + - "Animal injury requiring vet" + +**Expected response:** Same day or within hours. + +#### πŸ”„ routine +- **Color:** Gray (#CCCCCC) +- **Use for:** Regular tasks, normal priority, scheduled work +- **Examples:** + - "Weekly feeding schedule update" + - "Routine oil change" + - "Regular pasture rotation" + +**Expected response:** Within normal schedule (days to weeks). + +#### 🌱 seasonal +- **Color:** Yellow (#FBCA04) +- **Use for:** Tasks tied to specific seasons or weather +- **Examples:** + - "Spring planting preparation" + - "Winterize irrigation system" + - "Fall equipment storage" + +**Expected response:** Before season ends or deadline passes. + +--- + +### Status Labels +**What's blocking this task?** + +#### ⏳ waiting-on-parts +- **Color:** Light Gray (#EDEDED) +- **Use for:** Work delayed pending parts delivery +- **Examples:** + - "Tractor repair awaiting hydraulic hose" + - "Planter needs replacement disc blades" + +#### ☁️ waiting-on-weather +- **Color:** Cyan (#C2E0C6) +- **Use for:** Field work dependent on weather conditions +- **Examples:** + - "Field too wet to plant" + - "Rain delaying harvest" + - "Waiting for ground to freeze" + +#### πŸ₯ waiting-on-vet +- **Color:** Light Pink (#FFC0CB) +- **Use for:** Animal care pending veterinary visit +- **Examples:** + - "Scheduled vet visit next Tuesday" + - "Waiting for test results" + - "Pregnancy check scheduled" + +--- + +### Special Labels + +#### ❓ question +- **Color:** Light Purple (#D876E3) +- **Use for:** Questions, requests for information or clarification +- **Examples:** + - "What fertilizer rate for North 40?" + - "Which vet do we use for sheep?" + - "How to log equipment hours?" + +#### πŸ“š documentation +- **Color:** Teal (#0075CA) +- **Use for:** Updates to documentation, instructions, guides +- **Examples:** + - "Add new field to README" + - "Update equipment manual link" + - "Create how-to guide" + +#### πŸ€– automation +- **Color:** Dark Gray (#666666) +- **Use for:** Automated processes, workflows, bots +- **Examples:** + - "Weekly backup reminder" + - "Automated compliance deadline notification" + +#### πŸ†• enhancement +- **Color:** Bright Green (#84B6EB) +- **Use for:** Improvements, new features, suggestions +- **Examples:** + - "Add photos to equipment inventory" + - "Create seasonal calendar document" + - "Improve issue template" + +#### πŸ› bug +- **Color:** Dark Red (#D73A4A) +- **Use for:** Problems with repository, broken links, errors +- **Examples:** + - "Broken link in README" + - "Template not working correctly" + - "Formatting error in table" + +--- + +## Label Combinations + +Use multiple labels together for precise categorization: + +### Common Combinations + +**Equipment + Maintenance + Routine** +- Regular scheduled equipment service +- Example: "200-hour service on tractor" + +**Livestock + Health + Urgent** +- Emergency animal health situation +- Example: "Cow down, vet needed immediately" + +**Crops + Planning + Seasonal** +- Seasonal crop planning task +- Example: "Finalize spring planting schedule" + +**Compliance + Documentation + Waiting-on-** +- Compliance task with dependency +- Example: "Submit EQIP report (waiting for soil test results)" + +### Suggested Patterns + +| Task | Labels | +|------|--------| +| Broken tractor needs repair | equipment, repair, urgent | +| Plan next year's crops | crops, planning, seasonal | +| Annual vet visit scheduled | livestock, health, routine | +| Grant report due soon | compliance, documentation, seasonal | +| Field too wet to plant | crops, waiting-on-weather, seasonal | +| Fix fence before cattle arrive | equipment, repair, urgent | +| Update equipment manual | documentation, equipment, routine | + +--- + +## Label Best Practices + +### Do: +- βœ… Use multiple labels for better organization +- βœ… Apply domain label (crops/livestock/equipment/compliance) +- βœ… Apply type label (maintenance/repair/planning/etc.) +- βœ… Apply priority if relevant (urgent/routine/seasonal) +- βœ… Update labels as status changes +- βœ… Remove labels when no longer applicable + +### Don't: +- ❌ Over-label (too many labels = confusion) +- ❌ Use conflicting labels (e.g., urgent + routine) +- ❌ Forget to label issues +- ❌ Create new labels without discussion + +--- + +## Requesting New Labels + +If you need a label that doesn't exist: + +1. Open an issue with **question** label +2. Describe what label you need and why +3. Suggest a name and color +4. Explain what it would be used for + +Repository administrators will review and create if appropriate. + +--- + +## Related Resources + +- [How to Use GitHub Issues Effectively](../how-to/use-github-issues.md) +- [Getting Started Tutorial](../tutorials/getting-started.md) +- [Data Dictionary](./data-dictionary.md) + +--- + +**See all labels:** [GitHub Labels Page](https://github.com/zircote/github4farms-training/labels) diff --git a/docs/reference/naming-conventions.md b/docs/reference/naming-conventions.md new file mode 100644 index 0000000..6973220 --- /dev/null +++ b/docs/reference/naming-conventions.md @@ -0,0 +1,286 @@ +# File Naming Conventions + +Standards for naming files and directories in the Sunny Acres Farm repository. + +## General Principles + +### 1. Use Lowercase with Hyphens +**Format:** `word-word-word.md` + +**Good:** +- `planting-schedule.md` +- `health-records.md` +- `maintenance-log.md` + +**Bad:** +- `PlantingSchedule.md` (mixed case) +- `planting_schedule.md` (underscores) +- `plantingschedule.md` (no separators) + +**Why:** Consistent, web-friendly, readable, no case-sensitivity issues. + +### 2. Be Descriptive but Concise +**Aim for:** 2-4 words that clearly describe content + +**Good:** +- `soil-test-results.md` +- `feeding-schedule.md` +- `grant-tracker.md` + +**Bad:** +- `stuff.md` (too vague) +- `the-complete-and-comprehensive-livestock-feeding-schedule-for-all-animals.md` (too long) +- `doc1.md` (non-descriptive) + +**Why:** Makes it easy to find files and understand content at a glance. + +### 3. Use Plural for Collections +**When file contains multiple items**, use plural form. + +**Examples:** +- `certifications.md` (list of multiple certifications) +- `health-records.md` (multiple health record entries) +- `soil-test-results.md` (multiple test results) + +**But:** +- `crop-rotation-plan.md` (single plan document) +- `README.md` (single overview document) + +### 4. Date Formats in Filenames +**When including dates**, use ISO 8601 format: `YYYY-MM-DD` + +**Examples:** +- `soil-test-2026-03-15.md` +- `harvest-report-2026-10.md` +- `annual-summary-2026.md` + +**Why:** Sorts correctly, unambiguous, international standard. + +--- + +## Standard Filenames by Type + +### Index/Overview Files + +#### README.md +**Use for:** Directory overview, navigation aid, section introduction +**Location:** Root of any directory +**Content:** Description of directory contents, links to files, context + +**Example structure:** +````markdown +# Section Name + +Brief description of this section. + +## Contents + +| Document | Description | +|----------|-------------| +| [File Name](./filename.md) | What it contains | + +## Additional Context + +Any relevant information about this section. +```` + +### Record Files + +#### Standard Names +Use these standard names when applicable: + +**Crops:** +- `planting-schedule.md` +- `crop-rotation-plan.md` +- `soil-test-results.md` +- `harvest-records.md` +- `field-notes.md` + +**Livestock:** +- `health-records.md` +- `feeding-schedule.md` +- `veterinary-log.md` +- `breeding-records.md` +- `birth-records.md` + +**Equipment:** +- `maintenance-log.md` +- `safety-inspections.md` +- `inventory.md` +- `repair-history.md` +- `fuel-log.md` + +**Compliance:** +- `grant-tracker.md` +- `certifications.md` +- `inspection-reports.md` +- `annual-reports.md` + +### Temporary or Draft Files + +**Format:** `draft-filename.md` or `temp-filename.md` + +**Examples:** +- `draft-planting-plan-2027.md` +- `temp-soil-analysis.md` + +**Important:** Delete or rename to final name once finalized. + +### Archived Files + +**Format:** `filename-archived-YYYY.md` or move to `archive/` subdirectory + +**Examples:** +- `planting-schedule-archived-2025.md` +- `archive/2025/planting-schedule.md` + +**Use for:** Historical records that are no longer active but should be preserved. + +--- + +## Directory Naming + +### Main Directories +**Use lowercase, plural, no hyphens for top-level directories:** + +- `crops/` +- `livestock/` +- `equipment/` +- `compliance/` +- `docs/` + +**Why:** Short, simple, standard practice for repository organization. + +### Subdirectories +**Use lowercase with hyphens if needed:** + +- `docs/tutorials/` +- `docs/how-to/` +- `docs/reference/` +- `docs/explanation/` + +**Examples:** +- `crops/field-maps/` +- `equipment/service-manuals/` +- `livestock/breeding-records/` + +--- + +## Special Cases + +### GitHub-Specific Files + +**Must use exact capitalization:** + +- `README.md` (not readme.md or Readme.md) +- `LICENSE` (not license or license.txt) +- `CONTRIBUTING.md` (all caps) +- `CODE_OF_CONDUCT.md` (all caps) +- `SECURITY.md` (all caps) + +**Why:** GitHub recognizes these names and displays them specially. + +### Template Files + +**Use `.md` extension, descriptive names:** + +- `.github/ISSUE_TEMPLATE/equipment-maintenance.md` +- `.github/ISSUE_TEMPLATE/crop-issue-report.md` +- `.github/PULL_REQUEST_TEMPLATE.md` + +### Workflow Files + +**Agentic workflows use `.md` and `.lock.yml`:** + +- `.github/workflows/issue-triage.md` (source) +- `.github/workflows/issue-triage.lock.yml` (compiled, auto-generated) + +**Never edit `.lock.yml` files directly.** + +--- + +## What NOT to Include in Filenames + +### Avoid: +- ❌ Spaces: `planting schedule.md` β†’ breaks in URLs and command line +- ❌ Special characters: `health&records.md`, `soil@test.md` +- ❌ Underscores: `planting_schedule.md` (use hyphens instead) +- ❌ Mixed case: `PlantingSchedule.md` (use all lowercase) +- ❌ Version numbers: `schedule-v2.md` (use git for versioning) +- ❌ Personal names: `johns-notes.md` (use descriptive names) +- ❌ Abbreviations only: `ps.md`, `hr.md` (spell out) + +### Exception: +Some abbreviations are acceptable if widely understood: +- βœ… `usa.md` +- βœ… `faq.md` +- βœ… `api.md` + +--- + +## Renaming Files + +If you need to rename a file for consistency: + +### Process: +1. Create an issue explaining why rename is needed +2. Create a pull request with the rename +3. Update all links pointing to the old filename +4. Note the old filename in the PR description + +**Important:** Git tracks renames, so history is preserved. + +### Finding Links to Update: +````bash +# Search for old filename references +grep -r "old-filename.md" . +```` + +--- + +## Checklist for New Files + +Before creating a new file, verify: + +- [ ] Filename is lowercase with hyphens +- [ ] Filename is descriptive (2-4 words) +- [ ] Extension is `.md` for markdown +- [ ] Doesn't conflict with existing file +- [ ] Follows standard naming pattern if applicable +- [ ] No spaces, special characters, or underscores +- [ ] Will make sense to others 6 months from now + +--- + +## Examples by Scenario + +### Adding a new livestock record type: +**Good:** `lambing-records.md` +**Bad:** `Lambing.md`, `lambingRecords.md`, `lr.md` + +### Creating a seasonal plan: +**Good:** `spring-planting-plan-2027.md` +**Bad:** `SPP2027.md`, `plan.md`, `new plan.md` + +### Documenting equipment service: +**Good:** `equipment/tractors/service-schedule.md` +**Bad:** `equipment/Tractors/service.md`, `equipment/tractor_service.md` + +### Creating documentation: +**Good:** `docs/how-to/update-crop-records.md` +**Bad:** `docs/HowTo/updateCropRecords.md`, `docs/how to/update records.md` + +--- + +## Questions? + +- Unsure what to name a file? Open an issue with the **question** label +- See an inconsistently named file? Create a PR to fix it +- Want to propose a new naming standard? Start a discussion + +--- + +**See also:** +- [Data Dictionary](./data-dictionary.md) β€” Field naming standards +- [Repository Design](../explanation/repository-design.md) β€” Overall structure +- [How to Add a Crop Record](../how-to/add-crop-record.md) β€” Creating new records diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md new file mode 100644 index 0000000..b814e65 --- /dev/null +++ b/docs/tutorials/getting-started.md @@ -0,0 +1,124 @@ +# Getting Started with Sunny Acres Farm Repository + +**Tutorial Duration:** 15 minutes +**Level:** Beginner +**Prerequisites:** GitHub account + +## What You'll Learn + +In this tutorial, you'll learn how to: + +1. Navigate the farm repository +2. Find information about crops, livestock, equipment, and compliance +3. Create your first issue to report or request something +4. Understand the basic workflow + +## Step 1: Understanding the Repository Structure + +The Sunny Acres repository is organized like a filing cabinet with four main drawers: + +````markdown +github4farms-training/ +β”œβ”€β”€ crops/ # Everything about what we grow +β”œβ”€β”€ livestock/ # Everything about our animals +β”œβ”€β”€ equipment/ # Everything about our machinery +└── compliance/ # Everything about regulations and grants +```` + +**Try it yourself:** + +1. Go to the [repository homepage](https://github.com/zircote/github4farms-training) +2. Click on the **crops/** folder +3. You'll see several markdown (.md) files β€” these are farm records + +## Step 2: Reading a Farm Record + +Let's look at a planting schedule: + +1. From the **crops/** folder, click on **planting-schedule.md** +2. You'll see a table showing when different crops are planted in different fields + +**What you're seeing:** +- Field names (e.g., "North 40", "South Field") +- Crop types (corn, soybeans, wheat) +- Planting dates + +This is how all farm data is stored β€” in simple, readable text files. + +## Step 3: Finding Specific Information + +Let's say you need to know when the tractor was last serviced: + +1. Click the repository name at the top to go back to the main page +2. Click on **equipment/** +3. Click on **maintenance-log.md** +4. Scan the table for "John Deere 6120M Tractor" + +**Pro tip:** Use your browser's search function (Ctrl+F or Cmd+F) to quickly find specific equipment or dates. + +## Step 4: Creating Your First Issue + +Issues are how we track tasks, report problems, or ask questions. Let's create one: + +1. Go to the **Issues** tab (near the top of the page) +2. Click the green **New issue** button +3. Choose a template: + - **Crop Issue Report** β€” for planting, harvesting, or crop problems + - **Equipment Maintenance** β€” for equipment repairs or service + - **Livestock Health Record** β€” for animal health concerns + +4. Let's choose **Equipment Maintenance** +5. Fill in the form: + - **Title:** "Oil change for John Deere 6120M" + - **Equipment:** John Deere 6120M Tractor + - **Issue Type:** Routine Maintenance + - **Description:** "Tractor is due for 500-hour oil change" + +6. Click **Submit new issue** + +**Congratulations!** You just created your first farm record issue. + +## Step 5: Understanding Labels + +Your issue automatically got some labels (colored tags): + +- **equipment** β€” Shows this is about machinery +- **maintenance** β€” Shows it's a maintenance task +- **routine** β€” Shows the priority level + +Labels help organize and filter issues. You can click any label to see all similar issues. + +## Step 6: Exploring Other Sections + +Now explore the other sections on your own: + +- **livestock/** β†’ Find the feeding schedule +- **compliance/** β†’ See what grants are active +- **README.md** (root) β†’ Quick overview of everything + +## What's Next? + +Now that you understand the basics, try these tutorials: + +- [Creating Your First Issue](./creating-your-first-issue.md) β€” More detailed issue guidance +- [Recording Equipment Maintenance](./recording-equipment-maintenance.md) β€” Complete workflow example + +Or jump to practical tasks in the [How-To Guides](../how-to/). + +## Common Questions + +**Q: Can I edit files directly?** +A: Not directly on the main branch. You create a pull request to propose changes. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details. + +**Q: What if I make a mistake?** +A: Don't worry! Issues can be edited or closed. Pull requests can be updated. You can't break anything. + +**Q: Who sees my issues?** +A: Everyone with access to this repository. Keep information appropriate for your team. + +**Q: What if I need help?** +A: Open an issue with the "question" label or ask in Discussions. + +--- + +**You've completed the Getting Started tutorial!** You now know how to navigate the repository, read farm records, and create issues.