Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
236 lines (162 loc) · 6.18 KB

CONTRIBUTING.md

File metadata and controls

236 lines (162 loc) · 6.18 KB

Contributing to GitHub Copilot Dev Days Workshop Materials

Thank you for your interest in improving these workshop materials! This guide will help you contribute effectively.

🎯 Ways to Contribute

1. Report Issues

Found something that doesn't work or could be improved?

  • Typos or errors - Create an issue or PR directly
  • Unclear instructions - Explain what's confusing
  • Technical problems - Include environment details
  • Timing issues - Share if exercises ran too long/short

2. Improve Existing Content

  • Clarify instructions
  • Add examples or diagrams
  • Fix broken links
  • Update outdated information
  • Improve formatting

3. Add New Content

  • New workflow patterns
  • Additional exercises
  • Advanced topics
  • Translations/localizations
  • Slide deck templates
  • Video tutorials

4. Share Your Experience

Delivered the workshop? Please share:

  • What worked well
  • What needed adjustment
  • Participant feedback
  • Timing adjustments
  • Local adaptations

📋 Before You Contribute

Test Your Changes

  • If modifying exercises, test them yourself
  • Ensure commands work on the target platform
  • Verify links are valid
  • Check formatting renders correctly

Consider Impact

  • Will this change affect timing?
  • Does it require new prerequisites?
  • Is it appropriate for beginners?
  • Does it add value for facilitators?

🔄 Contribution Process

For Small Changes (Typos, Links, Formatting)

  1. Fork the repository
  2. Make your changes in a new branch
  3. Submit a pull request with clear description

For Larger Changes (New Content, Major Revisions)

  1. Open an issue first to discuss the change
  2. Get feedback from maintainers
  3. Make your changes in a new branch
  4. Submit a pull request referencing the issue

Pull Request Guidelines

Good PR Title Examples:

  • "Fix: Correct git command in participant handout"
  • "Add: New security audit workflow pattern"
  • "Update: Extend CI Doctor instructions"
  • "Docs: Clarify setup requirements for Windows"

PR Description Should Include:

  • What changed and why
  • Which files are affected
  • Testing performed
  • Impact on workshop timing (if applicable)
  • Screenshots (if relevant)

📝 Content Guidelines

Writing Style

  • Clear and concise - Workshop time is limited
  • Action-oriented - Tell people what to do
  • Inclusive language - Welcome all skill levels
  • Practical focus - Theory < Hands-on practice

Formatting

  • Use Markdown consistently
  • Include code blocks with proper syntax highlighting
  • Add checkpoints in exercises
  • Use emojis sparingly (they can help navigation)
  • Keep line length reasonable for readability

Commands and Code

  • Test all commands before committing
  • Include platform-specific versions when needed
  • Provide error handling guidance
  • Show expected output when helpful

Accessibility

  • Use descriptive link text (not "click here")
  • Provide alt text for images
  • Ensure high contrast in examples
  • Structure content with clear headings

🌍 Translations and Localizations

We welcome translations! Please:

  1. Create a new directory - e.g., translations/es/ for Spanish
  2. Translate key materials in this order:
    • participant-handout.md (most important)
    • quick-reference-card.md
    • gh-agentic-workflows-session.md
    • facilitator-guide.md (if resources allow)
  3. Keep technical terms - Don't translate: GitHub, Copilot, CLI, etc.
  4. Update main README - Add link to translated version

🎓 Workshop Pattern Library

Contributing workflow patterns? Ensure they:

Are Well Documented

  • Clear description of purpose
  • Prerequisites stated
  • Expected outcome described
  • Tested and verified working

Follow Template

### Pattern Name

**Use with:** [CLI/Cloud Agent/Repository Agent]

**Prompt:**

[Your detailed prompt here]


**Expected Result:**
- What the workflow will do
- What files it creates/modifies
- Typical execution time

**Common Issues:**
- Known problems and solutions

Are Practical

  • Solve a real problem
  • Appropriate for learning
  • Not overly complex
  • Generalizable to other projects

🚫 What Not to Contribute

Please don't submit:

  • Promotional content - No product pitches
  • Unrelated content - Stay focused on workshop delivery
  • Untested code - Always test before submitting
  • Copyrighted material - Only original or properly licensed content
  • Personal information - No emails, tokens, keys, etc.

🏷️ Issue and PR Labels

We use these labels to organize contributions:

  • enhancement - New features or improvements
  • bug - Something isn't working
  • documentation - Improvements to docs
  • good first issue - Good for newcomers
  • help wanted - Extra attention needed
  • question - Further information requested
  • translation - Non-English content
  • workshop-feedback - Reports from actual delivery

📞 Getting Help

Questions about contributing?

  • Open an issue with your question
  • Join GitHub Next Discord
  • Tag maintainers in discussions

Stuck on something?

  • Check existing issues for similar questions
  • Ask in GitHub Discussions
  • Be specific about what you need help with

🙏 Recognition

Contributors will be:

  • Listed in acknowledgments
  • Credited in commit history
  • Appreciated in release notes
  • Welcomed to the community

📄 License

By contributing, you agree that your contributions will be licensed under the same MIT License that covers this project.

🎉 Thank You!

Every contribution, no matter how small, makes these materials better for the community. Whether you're fixing a typo, adding a workflow pattern, or sharing feedback from your workshop—thank you for being part of this!

Questions? Open an issue or discussion.
Ready to contribute? Fork the repo and get started!
Just delivered a workshop? Share your experience!

Let's make GitHub Agentic Workflows accessible to everyone! 🚀