diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..76e0df0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,65 @@ +name: 🐛 Bug Report +description: Report an issue with course content, broken examples, or incorrect instructions +labels: [bug] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve this course! Please fill out the details below so we can fix the issue quickly. + + - type: dropdown + id: chapter + attributes: + label: Which chapter is affected? + options: + - "00 - Quick Start" + - "01 - First Steps" + - "02 - Context and Conversations" + - "03 - Development Workflows" + - "04 - Create Specialized AI Assistants" + - "05 - Automate Repetitive Tasks" + - "06 - Connect to GitHub, Databases & APIs" + - "07 - Putting It All Together" + - "Sample code (samples/)" + - "Appendices" + - "Other" + validations: + required: true + + - type: textarea + id: description + attributes: + label: What happened? + description: Describe the issue clearly. If a command or code example didn't work, include the exact text you copied. + placeholder: "When I ran the command from the 'Code Review' section, I got an error..." + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + placeholder: "I expected to see the code review output shown in the example..." + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Your OS, terminal, Copilot CLI version, and Python version + placeholder: | + - OS: macOS 15 / Windows 11 / Ubuntu 24.04 + - Terminal: iTerm2 / Windows Terminal / default + - Copilot CLI version: (run `copilot --version`) + - Python version: (run `python3 --version`) + validations: + required: false + + - type: textarea + id: screenshots + attributes: + label: Screenshots or terminal output + description: If applicable, paste terminal output or attach screenshots + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000..07cc61b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,48 @@ +name: 💡 Feature Request +description: Suggest new content, a new chapter topic, or an improvement to the course +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Have an idea to make this course better? We'd love to hear it! + + - type: dropdown + id: type + attributes: + label: What kind of improvement? + options: + - "New chapter or section" + - "New sample app or exercise" + - "Improve existing content" + - "Add a new agent or skill example" + - "Better explanation of a concept" + - "Other" + validations: + required: true + + - type: textarea + id: description + attributes: + label: Describe your idea + description: What would you like to see added or changed? Why would it help learners? + placeholder: "It would be helpful to have a section on..." + validations: + required: true + + - type: textarea + id: audience + attributes: + label: Who would benefit? + description: Is this for complete beginners, intermediate users, or a specific audience? + placeholder: "Beginners who are new to the terminal..." + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Have you seen this covered elsewhere? Is there a workaround? + validations: + required: false diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..b4cbb8b --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,70 @@ +# Copilot Instructions + +These instructions guide GitHub Copilot when working in this repository. + +## Project Context + +This is a **beginner-friendly educational course** teaching GitHub Copilot CLI. The repo contains Markdown chapters (00–07), Python/C#/JavaScript sample apps, and supporting assets (images, demo GIFs, glossary). It is **not** a software product — it is technical courseware. + +## Writing Conventions + +- **Audience**: Beginners with no AI/ML experience. Explain every technical term on first use. +- **Tone**: Friendly, encouraging, practical. Avoid jargon without explanation. +- **Examples**: All code blocks and `copilot` commands must be copy-paste ready. Test them mentally before including. +- **Naming**: Use kebab-case for session names, file names, and identifiers (e.g., `book-app-review`, not `book app review`). +- **Command syntax**: Standardize flag format — use `--flag=value` consistently when a value is required, `--flag` when boolean. +- **Precision**: Don't over-specify tool behavior that may vary across shells or OS. Describe what the user will see, not implementation details. +- **Fallbacks**: When referencing tool version requirements (e.g., `gh` CLI version), always include upgrade instructions or a manual alternative. + +## Content Conventions (from PR review patterns) + +These patterns were mined from actual PR review feedback and represent recurring maintainer expectations: + +- When showing multi-step workflows, ensure all prerequisite steps are included (e.g., `git add` before `git diff --staged`). +- When introducing a concept with an example, use consistent naming throughout the section — don't mix kebab-case and quoted names. +- When describing a command's behavior, match the level of specificity in the official release notes — don't state behavior that may differ across environments. +- If a feature requires a minimum tool version, mention the version AND provide a fallback path for users who can't upgrade yet. + +## Sample Code Conventions + +- **Primary sample**: Always use `samples/book-app-project/` (Python) for examples in chapters. +- **Test framework**: pytest — test files go in `samples/book-app-project/tests/` and follow `test_*.py` naming. +- **Python version**: 3.10+ (per `samples/book-app-project/pyproject.toml`). +- **Intentional bugs**: Files in `samples/book-app-buggy/` and `samples/buggy-code/` contain **deliberate bugs** for exercises. Never fix them. + +## Chapter Structure + +Every chapter (00–07) follows the same pattern in its `README.md`: + +1. Real-World Analogy +2. Core Concepts +3. Hands-On Examples +4. Assignment +5. What's Next + +Do not deviate from this structure when editing or adding chapter content. + +## Markdown Formatting + +- Use standard GitHub-Flavored Markdown. +- Images go in the repo-root `images/` directory. +- Use relative links for cross-chapter references (e.g., `../03-development-workflows/README.md`). +- Emoji usage is encouraged for section headers (matching existing style). + +## Maintenance Matrix + +| Change Made | Files to Update | +|---|---| +| New chapter added | `README.md` (course table), `AGENTS.md` (structure table), `images/learning-path.png` | +| Chapter content updated | The chapter's `README.md`, verify cross-references in adjacent chapters | +| New sample app variant added | `AGENTS.md` (structure table), `samples/` directory, relevant chapter references | +| Sample app code changed | `samples/book-app-project/tests/` (update/add tests), chapters referencing that code | +| Bug intentionally added to buggy samples | `samples/book-app-buggy/` or `samples/buggy-code/` only — do NOT update tests | +| New skill added | `.github/skills/{skill-name}/SKILL.md`, `samples/skills/` (example copy), Chapter 05 | +| New agent template added | `samples/agents/`, Chapter 04 | +| New MCP config added | `samples/mcp-configs/`, Chapter 06 | +| Glossary term introduced | `GLOSSARY.md` — add definition in alphabetical order | +| npm scripts changed | `package.json`, `AGENTS.md` (build section) | +| Devcontainer updated | `.devcontainer/devcontainer.json`, Chapter 00 (setup instructions) | +| Image or banner changed | `images/` directory, any README referencing the image | +| Copilot CLI version requirements change | Chapter 00, Chapter 01, `.devcontainer/devcontainer.json` | diff --git a/README.md b/README.md index ffd5ed2..4f2cd85 100644 --- a/README.md +++ b/README.md @@ -92,9 +92,19 @@ The **[GitHub Copilot CLI command reference](https://docs.github.com/en/copilot/ ## 🙋 Getting Help - 🐛 **Found a bug?** [Open an Issue](https://github.com/github/copilot-cli-for-beginners/issues) -- 🤝 **Want to contribute?** PRs welcome! - 📚 **Official Docs:** [GitHub Copilot CLI Documentation](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) +## Contributing + +> **Note**: The code used in the course is designed to generate specific types of output during reviews, explanations, and debugging so we aren't able to accept PRs that change the existing code. + +**How to contribute:** + +1. Fork this repository and clone it to your machine +2. Create a feature branch (`git checkout -b my-improvement`) +3. Make your changes +4. Submit a pull request + ## License This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.