Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
326 lines (233 loc) · 8.71 KB

CONTRIBUTING.md

File metadata and controls

326 lines (233 loc) · 8.71 KB
Raw

Contributing to GitHub Training Course

Thank you for your interest in improving this training course! This document provides guidelines for contributing.

🎯 How to Contribute

We welcome contributions in the following areas:

📝 Content Improvements

  • Fix typos, grammatical errors, or unclear explanations
  • Add missing information or examples
  • Update outdated content or links
  • Improve existing exercises or add new ones

🆕 New Content

  • Add new sections or topics
  • Create additional templates or examples
  • Develop supplementary materials
  • Translate content to other languages

🐛 Bug Reports

  • Report broken links or missing resources
  • Identify errors in code examples or instructions
  • Flag outdated information

💡 Suggestions

  • Propose new features or improvements
  • Share ideas for better organization
  • Suggest additional resources

📋 Contribution Process

For Small Changes (Typos, Minor Fixes)

  1. Navigate to the file you want to edit on GitHub
  2. Click the pencil icon (Edit this file)
  3. Make your changes directly in the browser
  4. Scroll down to "Commit changes"
  5. Add a descriptive commit message
    • Good: "Fix typo in Exercise 3 instructions"
    • Bad: "Update file"
  6. Select "Create a new branch for this commit and start a pull request"
  7. Click "Propose changes"
  8. Fill in the pull request template (see below)
  9. Submit the pull request

For Larger Changes (New Content, Major Revisions)

  1. Open an issue first to discuss your proposed changes

    • Describe what you want to add or change
    • Explain why it would be valuable
    • Wait for feedback before starting work

  2. Fork the repository (if you're not a collaborator)

    • Click "Fork" button on GitHub
    • Clone your fork to your computer (optional)

  3. Create a new branch for your changes

    • Name it descriptively: add-copilot-section or fix-exercise-4

  4. Make your changes

    • Follow the style guidelines below
    • Test any exercises or instructions
    • Update table of contents if needed

  5. Commit your changes with clear messages

    • Use present tense: "Add" not "Added"
    • Be specific about what changed

  6. Open a pull request

    • Fill in the template completely
    • Reference any related issues
    • Request review from maintainers

  7. Address feedback

    • Respond to comments
    • Make requested changes
    • Ask questions if unclear

  8. Celebrate! 🎉

    • Once approved and merged, your contribution is live!

✍️ Style Guidelines

Writing Style

  • Use clear, simple language - Write for non-technical audiences
  • Be concise - Get to the point quickly
  • Use active voice - "Click the button" not "The button should be clicked"
  • Include examples - Show, don't just tell
  • Be encouraging - Assume good intent and support learners

Formatting

  • Use Markdown for all documentation
  • Follow existing structure - Match the style of surrounding content
  • Use headings consistently
    • # for main titles
    • ## for major sections
    • ### for subsections
  • Use code blocks for commands, code, or file contents
    • Specify language: ```bash or ```yaml
  • Use tables for structured information
  • Use lists for steps or multiple items
  • Use bold for emphasis: **important**
  • Use italics for terms: *repository*
  • Use links to reference other sections or external resources

File Naming

  • Use lowercase letters
  • Separate words with hyphens: meeting-notes-template.md
  • Use descriptive names: github-security-guide.md not guide2.md
  • Use .md extension for Markdown files

Screenshots and Images

  • Use clear, high-resolution images
  • Annotate images to highlight key elements
  • Save in images/ folder
  • Use descriptive filenames: create-issue-button.png
  • Include alt text in markdown: ![Create Issue button](images/create-issue-button.png)

🧪 Testing Your Changes

Before submitting:

For Written Content

  • Read through your changes for clarity
  • Check spelling and grammar
  • Verify all links work
  • Ensure formatting displays correctly

For Exercises

  • Follow the steps yourself
  • Verify all instructions are accurate
  • Check that expected outcomes match reality
  • Test on a fresh account if possible

For Code/Workflows

  • Test the code or workflow
  • Verify it works as described
  • Check for any errors or warnings
  • Document any prerequisites

📝 Pull Request Template

When opening a pull request, please include:

## Summary
[Brief description of what this PR does]

## Type of Change
- [ ] Bug fix (typo, broken link, error correction)
- [ ] Content improvement (clarification, better examples)
- [ ] New content (new section, exercise, or resource)
- [ ] Documentation update
- [ ] Other (please describe)

## Changes Made
- [Change 1]
- [Change 2]
- [Change 3]

## Related Issues
Closes #[issue number]
Related to #[issue number]

## Testing
[Describe how you tested these changes]

## Screenshots (if applicable)
[Add screenshots to show visual changes]

## Checklist
- [ ] I have read the contributing guidelines
- [ ] My changes follow the style guidelines
- [ ] I have tested my changes
- [ ] I have updated relevant documentation
- [ ] My commit messages are clear and descriptive

🔍 Review Process

What Reviewers Look For

  • Accuracy - Is the information correct?
  • Clarity - Is it easy to understand?
  • Completeness - Is anything missing?
  • Consistency - Does it match the existing style?
  • Value - Does it improve the training?

Response Time

  • Small fixes: Usually reviewed within 2-3 days
  • Larger changes: May take up to a week
  • If no response after a week, feel free to ping reviewers

Approval Requirements

  • At least one approval from a maintainer
  • All comments addressed or discussed
  • No merge conflicts
  • Passes any automated checks

🏷️ Issue Labels

When creating issues, use these labels:

Label When to Use
bug Something is broken or incorrect
documentation Related to documentation improvements
enhancement New feature or improvement request
question Questions about the training
good first issue Good for new contributors
help wanted Extra attention needed
duplicate Issue already exists
wontfix Will not be addressed

🤝 Code of Conduct

Our Standards

  • Be respectful - Treat everyone with respect and kindness
  • Be constructive - Provide helpful feedback
  • Be inclusive - Welcome diverse perspectives
  • Be patient - Remember everyone is learning
  • Be professional - Keep discussions focused and productive

Unacceptable Behavior

  • Harassment or discrimination
  • Trolling or insulting comments
  • Personal or political attacks
  • Publishing others' private information
  • Other unprofessional conduct

Reporting

If you experience or witness unacceptable behavior:

  1. Contact the repository maintainers
  2. Provide details of the incident
  3. We will investigate and take appropriate action

💬 Communication Channels

For Contributions

  • Issues - Bug reports, feature requests, discussions
  • Pull Requests - Proposed changes
  • Discussions - General questions and conversations

For Questions

  • GitHub Discussions - Best for general questions
  • Issues - For specific problems or suggestions
  • Pull Request Comments - For feedback on proposed changes

🎓 Learning Resources for Contributors

New to contributing on GitHub? Check out:

🙏 Recognition

Contributors are recognized in several ways:

  • Listed in the repository's contributors page
  • Mentioned in release notes for significant contributions
  • Acknowledged in the README for major contributions
  • Eternal gratitude from learners who benefit from your work! 🌟

📞 Questions?

If you have questions about contributing:

  1. Check if your question is answered in this document
  2. Search existing issues and discussions
  3. Open a new discussion in the Q&A category
  4. Contact the maintainers directly if needed

📄 License

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

Thank you for helping make this training better for everyone! 🚀

Last Updated: October 2025
Maintained by: Training Team