[feb 18 merge] feat(guide): social elements of github and oss

contribute-open-source/index.md

@@ -128,6 +128,7 @@ resources
 :hidden:
 
 About These Lessons  <self>
+Social Etiquette in Open Source  <social-open-source>
 
 :::
 
@@ -158,7 +159,6 @@ Clone a GitHub Repo <clone-repo>
 :hidden:
 
 What is Git/GitHub <what-is-git-github>
-GitHub Social platform <github-social-platform>
 Use GitHub codespaces <github-codespaces>
 Ways to contribute <ways-to-contribute>
 :::

contribute-open-source/social-open-source.md

@@ -0,0 +1,205 @@
+---
+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 to help them feel confident and welcome** 
+* **2️⃣ Develop contributing documentation that outlines the types of contributions you can support**
+* **3️⃣ Acknowledge contributors and their contributions** 
+:::
+
+## <i class="fa-solid fa-users"></i> For contributors 
+
+### 1️⃣ Engage thoughtfully in open source communities 
+
+Since most GitHub collaboration is asynchronous, effective communication ensures your contributions are received well and help move projects forward. Learn how to interact professionally in issues, pull requests, and discussions to make collaboration smooth and efficient. 
+
+#### <i class="fa-solid fa-list-check"  style="color: #81c0aa;"></i> 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 ready** for your change.  
+  - Opening an issue first allows maintainers to **guide your work before you start coding**.  
+
+---
+
+#### <i class="fa-solid fa-book-open"  style="color: #81c0aa;"></i> 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 for both you and the maintainers**.  
+
+---
+
+#### <i class="fa-solid fa-handshake-angle"  style="color: #81c0aa;"></i> 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**.  
+
+- **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.
+
+#### <i class="fa-solid fa-user-check" style="color: #81c0aa;"></i> 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.  
+
+#### <i class="fa-solid fa-cubes" style="color: #81c0aa;"></i> 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 add 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**.  
+
+### <i class="fa-solid fa-user-plus" style="color: #81c0aa;"></i> 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.  
+  - If you can’t finish something, let them know so someone else can pick it up.   
+
+---
+
+## <i class="fa-solid fa-users"></i> 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.  
+
+---
+
+### 1️⃣ <i class="fa-solid fa-handshake-angle" style="color: #81c0aa;"></i> 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️⃣ <i class="fa-solid fa-book-open" style="color: #81c0aa;"></i> 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️⃣ <i class="fa-solid fa-hands-clapping" style="color: #81c0aa;"></i> 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!

index.md

@@ -18,16 +18,14 @@ Learn how to navigate the technical and social elements of making a contribution
 
 * [Your First Contribution](pyos-first-contribution)
 * [Get to know a new repo](new-repo)
-* [Find an issue to work on](identify-github-issue) 
-* [Fork a repo](fork-repository) 
+* [Find an issue to work on](identify-github-issue)
+* [Fork a repo](fork-repository)
 * [Edit & commit files](pyos-edit-commit-files)
 * [Submit a pull request](pyos-pull-request)
 
 :::
 ::::
 
-
-
 ::::{grid-item}
 :::{card} ✿ Clean Code ✿
 :class-card: left-aligned
@@ -59,7 +57,6 @@ TODO: let's merge this with the conditional lesson
 :::
 ::::
 
-
 ::::{grid-item}
 :::{card} ✿ Package & Share Your Code ✿
 :class-card: left-aligned
@@ -72,8 +69,6 @@ TODO: let's merge this with the conditional lesson
 :::
 ::::
 
-
-
 :::::
 
 ## Who are these lessons for
@@ -86,13 +81,12 @@ code using best practices and tools.
 
 :::{toctree}
 :hidden:
-:caption: Write Better Code 
+:caption: Write Better Code
 :maxdepth: 2
 
 Write Better Code <write-better-code/index>
 :::
 
-
 :::{toctree}
 :hidden:
 :caption: Package & Share Code
@@ -101,15 +95,10 @@ Write Better Code <write-better-code/index>
 Package & Share Code <package-share-code/index>
 :::
 
-
 :::{toctree}
 :hidden:
 :caption: GitHub
 :maxdepth: 2
 
 Contribute Open Source <contribute-open-source/index>
 :::
-
-:::{todolist}
-
-:::