Skip to content

Commit 65551fc

Browse files
DanWahlinDanWahlin
committed
feat: add bug report and feature request issue templates; enhance README with contributing guidelines and Copilot instructions
1 parent 7c0df5a commit 65551fc

4 files changed

Lines changed: 195 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: 🐛 Bug Report
2+
description: Report an issue with course content, broken examples, or incorrect instructions
3+
labels: [bug]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for helping improve this course! Please fill out the details below so we can fix the issue quickly.
9+
10+
- type: dropdown
11+
id: chapter
12+
attributes:
13+
label: Which chapter is affected?
14+
options:
15+
- "00 - Quick Start"
16+
- "01 - First Steps"
17+
- "02 - Context and Conversations"
18+
- "03 - Development Workflows"
19+
- "04 - Create Specialized AI Assistants"
20+
- "05 - Automate Repetitive Tasks"
21+
- "06 - Connect to GitHub, Databases & APIs"
22+
- "07 - Putting It All Together"
23+
- "Sample code (samples/)"
24+
- "Appendices"
25+
- "Other"
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: description
31+
attributes:
32+
label: What happened?
33+
description: Describe the issue clearly. If a command or code example didn't work, include the exact text you copied.
34+
placeholder: "When I ran the command from the 'Code Review' section, I got an error..."
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: expected
40+
attributes:
41+
label: What did you expect to happen?
42+
placeholder: "I expected to see the code review output shown in the example..."
43+
validations:
44+
required: true
45+
46+
- type: textarea
47+
id: environment
48+
attributes:
49+
label: Environment
50+
description: Your OS, terminal, Copilot CLI version, and Python version
51+
placeholder: |
52+
- OS: macOS 15 / Windows 11 / Ubuntu 24.04
53+
- Terminal: iTerm2 / Windows Terminal / default
54+
- Copilot CLI version: (run `copilot --version`)
55+
- Python version: (run `python3 --version`)
56+
validations:
57+
required: false
58+
59+
- type: textarea
60+
id: screenshots
61+
attributes:
62+
label: Screenshots or terminal output
63+
description: If applicable, paste terminal output or attach screenshots
64+
validations:
65+
required: false

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: 💡 Feature Request
2+
description: Suggest new content, a new chapter topic, or an improvement to the course
3+
labels: [enhancement]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Have an idea to make this course better? We'd love to hear it!
9+
10+
- type: dropdown
11+
id: type
12+
attributes:
13+
label: What kind of improvement?
14+
options:
15+
- "New chapter or section"
16+
- "New sample app or exercise"
17+
- "Improve existing content"
18+
- "Add a new agent or skill example"
19+
- "Better explanation of a concept"
20+
- "Other"
21+
validations:
22+
required: true
23+
24+
- type: textarea
25+
id: description
26+
attributes:
27+
label: Describe your idea
28+
description: What would you like to see added or changed? Why would it help learners?
29+
placeholder: "It would be helpful to have a section on..."
30+
validations:
31+
required: true
32+
33+
- type: textarea
34+
id: audience
35+
attributes:
36+
label: Who would benefit?
37+
description: Is this for complete beginners, intermediate users, or a specific audience?
38+
placeholder: "Beginners who are new to the terminal..."
39+
validations:
40+
required: false
41+
42+
- type: textarea
43+
id: alternatives
44+
attributes:
45+
label: Alternatives considered
46+
description: Have you seen this covered elsewhere? Is there a workaround?
47+
validations:
48+
required: false

‎.github/copilot-instructions.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Copilot Instructions
2+
3+
These instructions guide GitHub Copilot when working in this repository.
4+
5+
## Project Context
6+
7+
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.
8+
9+
## Writing Conventions
10+
11+
- **Audience**: Beginners with no AI/ML experience. Explain every technical term on first use.
12+
- **Tone**: Friendly, encouraging, practical. Avoid jargon without explanation.
13+
- **Examples**: All code blocks and `copilot` commands must be copy-paste ready. Test them mentally before including.
14+
- **Naming**: Use kebab-case for session names, file names, and identifiers (e.g., `book-app-review`, not `book app review`).
15+
- **Command syntax**: Standardize flag format — use `--flag=value` consistently when a value is required, `--flag` when boolean.
16+
- **Precision**: Don't over-specify tool behavior that may vary across shells or OS. Describe what the user will see, not implementation details.
17+
- **Fallbacks**: When referencing tool version requirements (e.g., `gh` CLI version), always include upgrade instructions or a manual alternative.
18+
19+
## Content Conventions (from PR review patterns)
20+
21+
These patterns were mined from actual PR review feedback and represent recurring maintainer expectations:
22+
23+
- When showing multi-step workflows, ensure all prerequisite steps are included (e.g., `git add` before `git diff --staged`).
24+
- When introducing a concept with an example, use consistent naming throughout the section — don't mix kebab-case and quoted names.
25+
- 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.
26+
- If a feature requires a minimum tool version, mention the version AND provide a fallback path for users who can't upgrade yet.
27+
28+
## Sample Code Conventions
29+
30+
- **Primary sample**: Always use `samples/book-app-project/` (Python) for examples in chapters.
31+
- **Test framework**: pytest — test files go in `samples/book-app-project/tests/` and follow `test_*.py` naming.
32+
- **Python version**: 3.10+ (per `pyproject.toml`).
33+
- **Intentional bugs**: Files in `samples/book-app-buggy/` and `samples/buggy-code/` contain **deliberate bugs** for exercises. Never fix them.
34+
35+
## Chapter Structure
36+
37+
Every chapter (00–07) follows the same pattern in its `README.md`:
38+
39+
1. Real-World Analogy
40+
2. Core Concepts
41+
3. Hands-On Examples
42+
4. Assignment
43+
5. What's Next
44+
45+
Do not deviate from this structure when editing or adding chapter content.
46+
47+
## Markdown Formatting
48+
49+
- Use standard GitHub-Flavored Markdown.
50+
- Images go in the repo-root `images/` directory.
51+
- Use relative links for cross-chapter references (e.g., `../03-development-workflows/README.md`).
52+
- Emoji usage is encouraged for section headers (matching existing style).
53+
54+
## Maintenance Matrix
55+
56+
| Change Made | Files to Update |
57+
|---|---|
58+
| New chapter added | `README.md` (course table), `AGENTS.md` (structure table), `images/learning-path.png` |
59+
| Chapter content updated | The chapter's `README.md`, verify cross-references in adjacent chapters |
60+
| New sample app variant added | `AGENTS.md` (structure table), `samples/` directory, relevant chapter references |
61+
| Sample app code changed | `samples/book-app-project/tests/` (update/add tests), chapters referencing that code |
62+
| Bug intentionally added to buggy samples | `samples/book-app-buggy/` or `samples/buggy-code/` only — do NOT update tests |
63+
| New skill added | `.github/skills/{skill-name}/SKILL.md`, `samples/skills/` (example copy), Chapter 05 |
64+
| New agent template added | `samples/agents/`, Chapter 04 |
65+
| New MCP config added | `samples/mcp-configs/`, Chapter 06 |
66+
| Glossary term introduced | `GLOSSARY.md` — add definition in alphabetical order |
67+
| npm scripts changed | `package.json`, `AGENTS.md` (build section) |
68+
| Devcontainer updated | `.devcontainer/devcontainer.json`, Chapter 00 (setup instructions) |
69+
| Image or banner changed | `images/` directory, any README referencing the image |
70+
| Copilot CLI version requirements change | Chapter 00, Chapter 01, `.devcontainer/devcontainer.json` |

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
![GitHub Copilot CLI for Beginners](./images/copilot-banner.png)
22

3+
[![AI Ready](https://img.shields.io/badge/AI--Ready-yes-brightgreen?style=flat)](https://github.com/johnpapa/ai-ready)
34
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) 
45
[![Open project in GitHub Codespaces](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/github/copilot-cli-for-beginners?hide_repo_select=true&ref=main&quickstart=true) 
56
[![Official Copilot CLI documentation](https://img.shields.io/badge/GitHub-CLI_Documentation-00a3ee?style=flat-square&logo=github)](https://docs.github.com/en/copilot/how-tos/copilot-cli) 
@@ -95,6 +96,17 @@ The **[GitHub Copilot CLI command reference](https://docs.github.com/en/copilot/
9596
- 🤝 **Want to contribute?** PRs welcome!
9697
- 📚 **Official Docs:** [GitHub Copilot CLI Documentation](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)
9798

99+
## Contributing
100+
101+
> **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.
102+
103+
**How to contribute:**
104+
105+
1. Fork this repository and clone it to your machine
106+
2. Create a feature branch (`git checkout -b my-improvement`)
107+
3. Make your changes
108+
4. Submit a pull request
109+
98110
## License
99111

100112
This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.

0 commit comments

Comments
 (0)