Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
260 lines (192 loc) · 6.77 KB

CONTRIBUTING.md

File metadata and controls

260 lines (192 loc) · 6.77 KB

Contributing to the Git & GitHub Tutorial

Thank you for your interest in improving this educational repository! This guide will help you contribute effectively.

🎯 Types of Contributions Welcome

Documentation Improvements

  • Fix typos or grammatical errors
  • Clarify confusing explanations
  • Add missing information
  • Improve formatting and readability

Tutorial Enhancements

  • Add new examples or exercises
  • Suggest better learning progressions
  • Create additional practice scenarios
  • Improve existing explanations

Bug Reports

  • Report broken links
  • Identify outdated information
  • Point out incorrect Git commands
  • Note missing prerequisites

New Content

  • Additional tutorials for advanced topics
  • New sample projects
  • More troubleshooting scenarios
  • Translation into other languages

🚀 How to Contribute

For Beginners (Perfect for practicing Git!)

  1. Fork this repository

    • Click the "Fork" button on GitHub
    • This creates your own copy of the repository

  2. Clone your fork

    git clone https://github.com/yourusername/github_ds1001.git
cd github_ds1001

  3. Create a new branch

    git checkout -b improve-tutorial-explanation

  4. Make your changes

    • Edit files using your favorite text editor
    • Test any new exercises or commands
    • Follow the style guidelines below

  5. Commit your changes

    git add .
git commit -m "Improve explanation of staging area concept"

  6. Push to your fork

    git push origin improve-tutorial-explanation

  7. Create a Pull Request

    • Go to your fork on GitHub
    • Click "Compare & pull request"
    • Fill out the template (see below)

For Experienced Contributors

  • Feel free to work on multiple issues simultaneously
  • Consider mentoring newer contributors
  • Help review pull requests from others
  • Suggest architectural improvements

📝 Pull Request Template

When creating a pull request, please include:

## What does this PR do?
Brief description of your changes

## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Documentation update
- [ ] Tutorial improvement
- [ ] Exercise addition/improvement

## Testing
- [ ] I have tested the Git commands in the tutorials
- [ ] I have checked for typos and grammatical errors
- [ ] I have verified that links work correctly
- [ ] New exercises have been tested by following them step-by-step

## Additional context
Any other information about your changes

📋 Style Guidelines

For Tutorials and Documentation

Writing Style:

  • Use clear, beginner-friendly language
  • Include real-world examples and analogies
  • Explain the "why" behind Git concepts, not just the "how"
  • Use active voice when possible

Formatting:

  • Use consistent heading levels (# for main titles, ## for sections)
  • Include code blocks with proper syntax highlighting
  • Use bullet points for lists and steps
  • Add emojis sparingly for visual breaks

Git Commands:

  • Show commands in code blocks: git status
  • Include expected output when helpful
  • Explain what each command does
  • Provide context for when to use commands

Example of Good Tutorial Content:

## Understanding Git Status 📊

The `git status` command is like asking Git "What's happening in my repository right now?"

### When to use it:
- Before making commits (to see what will be included)
- When you're confused about the current state
- After making changes (to see what Git detected)

### Try it yourself:
```bash
git status

You should see output like:

On branch main
nothing to commit, working tree clean

This means you're on the main branch and have no changes to commit.


### For Code Examples

**Sample Projects:**
- Use realistic but simple examples
- Include comments explaining key concepts
- Make sure all code works as expected
- Follow web standards for HTML/CSS

**Exercise Instructions:**
- Break complex tasks into small steps
- Include verification steps ("You should see...")
- Provide troubleshooting for common issues
- Add "Extra Credit" challenges for advanced learners

## 🐛 Reporting Issues

### Before Creating an Issue

1. **Search existing issues** to avoid duplicates
2. **Try the troubleshooting guide** first
3. **Test with a fresh repository** to isolate the problem

### Issue Template

Problem Description

What went wrong? What did you expect to happen?

Steps to Reproduce

  1. Go to tutorial/exercise X
  2. Run command Y
  3. See error Z

Environment

  • Operating System: (Windows/Mac/Linux)
  • Git Version: (run git --version)
  • Tutorial/Exercise: (which one?)

Additional Context

Screenshots, error messages, or other helpful information


## 🔍 Review Process

### What We Look For

**Quality:**
- Accurate information
- Clear explanations
- Working examples
- Proper formatting

**Educational Value:**
- Appropriate for the target audience
- Builds on previous concepts
- Includes practice opportunities
- Connects to real-world usage

### Review Timeline

- **Simple fixes** (typos, formatting): Usually reviewed within 1-2 days
- **Content additions**: May take 3-7 days for thorough review
- **Major changes**: Could require multiple rounds of feedback

## 🏆 Recognition

Contributors will be recognized in several ways:

### Hall of Fame
Complete the tutorials and exercises, then add your name to [HALL_OF_FAME.md](HALL_OF_FAME.md)

### Contributor Credits
Significant contributors will be mentioned in the README

### GitHub Recognition
All contributions are tracked in GitHub's contributor graph

## 📚 Resources for Contributors

### Understanding the Audience
This repository targets:
- Students new to version control
- Developers learning Git for the first time
- Anyone wanting to understand GitHub workflows
- Educators looking for Git curriculum

### Learning More About Git
- [Pro Git Book](https://git-scm.com/book) (free online)
- [Git Documentation](https://git-scm.com/doc)
- [GitHub Learning Lab](https://lab.github.com/)

### Markdown Reference
- [GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/)
- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)

## ❓ Questions?

- **General questions:** [Create an issue](https://github.com/NovaVolunteer/github_ds1001/issues)
- **Want to discuss big changes:** Start with an issue before working
- **Need help with Git:** Check our [troubleshooting guide](troubleshooting/README.md)

## 🎉 Thank You!

Every contribution, no matter how small, helps make this resource better for learners everywhere. We appreciate your time and effort!

---

**Happy Contributing! 🚀**

*Remember: Contributing to this repository is a great way to practice the Git workflows you're learning!*