--- jupytext: text_representation: extension: .md format_name: myst format_version: 0.13 jupytext_version: 1.16.4 kernelspec: display_name: Python 3 (ipykernel) language: python name: python3 myst_html_meta: "title": "The social side of open source: Engage, build trust & support contributors" "description lang=en": "A guide to the social elements that will make contributing to open source more impactful, valuable, and successful." "keywords": "GitHub, OpenSource, beginner-friendly" "property=og:locale": "en_US" --- (social-github)= # The social side of open source: Engage, build trust & support contributors :::{figure} /images/github/open-source-social-network.png :alt: A digital illustration visualizing open-source collaboration on GitHub. At the center, a “Main Repo” connects to contributors performing key actions: forking (branching icon), submitting pull requests (PRs) (merge arrows), reviewing code (magnifying glass over documents), and engaging in discussions (speech bubbles and coding icon). The pyOpenSci logo appears in the bottom right, reinforcing the theme of community-driven contributions. ::: ## Why social etiquette matters in open source Contributing to open source isn’t just about code—it’s about **collaborating with people you may never meet in real life**. Unlike traditional in-person workplaces, GitHub interactions happen asynchronously, across time zones, and often with volunteers who have many different life priorities. This means **how you communicate is just as important as what you contribute**. :::{admonition} Key Takeaways For contributors: * **1️⃣ Engage thoughtfully in open source communities** * **2️⃣ Start small and contribute sustainably** * **3️⃣ Build trust through transparent collaboration** For maintainers: * **1️⃣ Support contributors by building a welcoming project** * **2️⃣ Develop contributing documentation to guide contributors to success** * **3️⃣ Acknowledge contributors and their contributions** ::: ## For contributors ### 1️⃣ Engage thoughtfully in open source communities Since most GitHub collaboration is asynchronous, effective communication ensures your contributions follow the project norms, increase the value of your contribution, and help move projects forward. Learn how to interact professionally in issues, pull requests, and discussions to make collaboration smooth and efficient. #### Keep maintainers informed - **Open an issue before submitting a pull request (PR).** - Maintainers **need to track who is working on what**. - If an issue already exists, **comment instead of opening a new one**. - **Avoid surprising maintainers with an unexpected PR.** - Some projects **may not be receptive** to your change. For example, your suggested change may be out of the project's scope or conflict with the project's future direction. - Opening an issue first allows maintainers to **offer feedback and guide your work before you start coding**. --- #### Respect the project’s workflow - **Follow contribution guidelines.** - Many projects have structured templates for submitting issues—**use them** to provide the right details. - If a project has contribution guidelines, reference them to show you’re **aligning with their process**. - **Ask before making major changes.** - A simple *“Would this be useful?”* in an issue can save **time and frustration for you and the maintainers**. --- #### Communicate professionally - **Be patient and respectful.** - Many maintainers **volunteer their time**—make your requests **clear and easy to understand**. - If you're waiting on a response, give it time before **politely following up**. - Maintainers understand that you are excited to receive a response, yet they may also have many additional requests. Please respect their effort and timelines. - **Be concise and avoid unnecessary comments.** - We live in an age of too many notifications. Keep your responses short, polite and to the point. - If it's appropriate, instead of commenting **“+1”** or “I agree,” use 👍 or ❤️ to acknowledge messages. --- ### 2️⃣ Start small and contribute sustainably Contributing should be sustainable, not overwhelming. **Starting small** helps you build confidence, keep efforts manageable, and establish credibility with maintainers. Even minor contributions add up over time and can lead to greater opportunities. - **Start small to build confidence.** - First contributions don’t have to be big—**fixing typos or improving docs** is a great start. Just make sure that the project that you're contributing to welcomes these types of contributions before starting one! - These small changes **help the project** and **show maintainers that you’re engaged**. - If the project you are looking to contribute to has **good first issues**, these are an excellent way to get started. Those are issues the maintainers marked as being good for onboarding; find them by filtering for that label in the Issues section. - When making changes, try to keep them small and scoped to one topic or area. This results in better code reviews and often faster responses. #### Start small - **Begin with small, manageable contributions.** - **Fixing typos, improving documentation, or tackling minor issues** are great first steps. Just be sure that the project **welcomes small contributions** before starting one. - If in doubt, review the project's Contributors' Guide. #### Follow through and build credibility * **Be consistent and follow through** helps you build trust with the maintainer team. - As maintainers recognize your efforts, **they may also review your work more quickly**. * **Contributions and trust adds up over time.** - Even small contributions build credibility. And they will help you build skills and confidence needed to contribute more in the future ### 3️⃣ Build trust through transparent collaboration Trust helps your contributions get reviewed and merged faster and builds on top of thoughtful engagement. Through trust, you can communicate to maintainers that you are a reliable contributor. Trust is the foundation of all collaboration—especially in open source, where maintainers may not know you yet. Since your **first impression happens through issues, PRs, and comments**, it’s important to show that you’re **thoughtful, respectful, and mindful of the maintainers’ time**. ### How contributors can build trust - **Introduce yourself when commenting on an issue.** - A quick hello makes it easier to start contributing. - Example: > “Hey everyone! 👋 Thank you for your work on this project. I’m new to contributing here and would love to help with this issue. Let me know if there’s anything I should consider before getting started!” - **Be transparent about what you’re working on.** - If you start working on an issue, leave a comment so others know. - Example: > “I’d love to take this on! I’ll start by updating the docs and submit a PR soon.” - **Follow the project’s workflow and be responsive.** - Maintain good communication—if a maintainer asks for changes, reply and iterate. - Keep the communication focused on the code and not the person. For example, responding "you're wrong" is not helpful; instead, calmly explain the technical approach you took and asking for "Thoughts?" or "Additional ideas" will result in improving the project through respectful collaboration. - If you can’t finish something, let them know so someone else can pick it up. --- ## For maintainers: Support, document, and acknowledge contributors Many contributors hesitate to get involved due to **imposter syndrome or fear of making mistakes**. Maintainers and experienced contributors can help by making GitHub feel more accessible. If you have the bandwidth, try to be welcoming and supportive. If you don't have bandwidth, it's ok-—gently nudge new contributors toward beginner-friendly projects or helpful resources. If you don't have time personally to review a PR, it's better to acknowledge it "Thanks for your PR. I'm currently unable to review. If another maintainer can take a look, I would appreciate it." :::{tip} If a new contributor contributes something to your project. Consider, inviting them to make another contribution in the future. This is a great way to build a community of contributors over time that consistently give back to your project. ::: --- ### 1️⃣ Support contributors to help them feel confident and welcome - **Be welcoming to new contributors.** - A simple “Thanks for your interest!” or “Happy to have you here!” makes a big difference. - Example: > “Welcome! 🚀 This is a great first issue to start with—let us know if you need any help.” - **Encourage small contributions.** - Many first-time contributors start with minor fixes—support their effort, even if small. - **Be patient and approachable.** - GitHub can be intimidating—help create an environment where people feel comfortable asking questions. - **Give constructive, actionable feedback.** - If a PR needs changes, explain **why** so contributors learn and improve. - Example: > “This is a great start! Could you also update the docs so future users understand this change?” --- ### 2️⃣ Develop contributing documentation - **Outline the types of contributions you can support.** - Make it clear whether your project welcomes **docs updates, bug fixes, feature requests, or other improvements**. - A well-structured [`CONTRIBUTING.md` file](https://www.pyopensci.org/python-package-guide/documentation/repository-files/contributing-file.html) helps newcomers understand how to get started and tells them the types of contributions that you welcome. - **Use issue labels to guide contributors.** - Tags like `good first issue` or `help wanted` signal beginner-friendly opportunities. - **Provide a contribution workflow.** - If your project has a preferred PR process, document it and link to it in your contributing guidelines to streamline collaboration. --- ### 3️⃣ Acknowledge contributors and their contributions - **Recognize and appreciate contributions.** - A “Thank you!” comment or merging a small PR quickly **builds confidence**. - If you can, add contributors to a **README, acknowledgments file, or a contributors list**. - Acknowledge new contributors to GitHub release notes ```md [v0.3.4] - 2024-08-01 Fixes Fix: Edit .env-default file to correct syntax (@new-contributor, #196) ✨ Thank you to the new contributors in this release ✨ @new-contributor ``` - **Use automation to acknowledge contributions.** - Tools like the [**All Contributors bot**](https://allcontributors.org/) help recognize all types of contributions, including **code, issue triage, documentation, and discussions**—not just commit history. This ensures that contributors get credit for their impact beyond code changes. --- ## Summary: The social side of open source Open source is truly more than just about code. It's about building trust and relationships and, for new contributors, great opportunities to learn and build social, technical, and even management skills. Following these best practices will set yourself up for great success when navigating the open source community. And in the process, you may even pick up some lifelong friends along the way!