Community Interaction Best Practices on GitHub#

🚧 These lessons are under heavy construction and will continue to change through March 2024 🚧

Introduction#

GitHub is more than just a platform for hosting code—it’s a social platform where developers, researchers, and contributors work together to create, improve, and share projects. Behind every username is a person who deserves respect and appreciation.

This lesson will teach you how to interact constructively and positively within the GitHub community. Whether submitting an issue, reviewing someone else’s work, or asking for help, following these best practices will help you collaborate effectively and maintain a welcoming environment.

Communication principles and best practices#

Effective communication on GitHub ensures a productive and respectful collaboration environment. Whether you’re raising an issue, reviewing code, or contributing to a discussion, these principles will help you interact constructively.

Respect and professionalism#

  • Treat everyone with respect, even when disagreements arise.

  • Remember that many maintainers and contributors volunteer their time and expertise to the community.

  • Use polite and appreciative language when reaching out or giving feedback.
    Example: “Thank you for creating this tool. It’s been really helpful!”

Patience#

  • Be understanding if responses to issues or pull requests take time.

  • Open-source maintainers often juggle multiple responsibilities outside their projects.

Clarity and thoughtfulness#

  • Use clear and concise language:

    • Clearly describe issues, bugs, or suggestions to avoid confusion.

    • Avoid unnecessary jargon or overcomplicating explanations.

  • Tag people thoughtfully:

    • Use @username mentions sparingly to notify specific contributors or maintainers.

    • Avoid overusing mentions or tagging unrelated individuals.

  • Use GitHub features wisely:

    • Add meaningful comments that contribute to the discussion.

    • Use reactions (like đź‘Ť or ❤️) to express agreement or appreciation without cluttering threads with “+1” comments.

Constructive feedback#

  • Avoid harsh language, blame, or criticism.

  • Frame suggestions as questions or alternatives:
    “What if we try this approach?” instead of “This is wrong.”

  • Acknowledge positive aspects alongside suggestions for improvement.

3. When Contributing to a Repository#

Submitting Issues#

  • Search First: Before creating a new issue, check if someone else has already reported it.

  • Be Clear: Provide a detailed, reproducible example when reporting bugs.

  • Be Constructive: Avoid blaming or harsh criticism. Instead, frame your concerns as suggestions.

Example:
Not Constructive: “This feature is broken and useless.”
Constructive: “I encountered an issue when using this feature. Here’s the error and steps to reproduce it.”

Opening Pull Requests#

  • Describe the Change: Clearly explain what you’re proposing and why it’s needed.

  • Follow Contribution Guidelines: Adhere to any style or workflow rules outlined in the repository.

  • Be Open to Feedback: Expect to receive suggestions for improvement and revise your pull request accordingly.

Example Pull Request Description: