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

lwasser · 2025-01-31T22:38:32Z

this is a rewrite to the social page. The next step will be cross linking content in this page.

sneakers-the-rat · 2025-02-01T08:48:52Z

github-git/social-open-source.md

+
+## 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 workplaces, GitHub interactions happen asynchronously, across time zones, and often with volunteers.  


excited to dive into this tmrw. love this so much

@sneakers-the-rat yay! yes my goal with these lessons is to not just teach the technical steps, but also to help people learn that stuff that you and I and others learn "the hard way" by doing it over time. That is part of what I think triggers fear and nervousness. By having our community review all of these lessons, I think collectively, we can pull together our knowledge to make these lessons really great.

the goal with this page is to pull together all of the tips we provide on the other pages into a single page as a high level summary.

hamogu · 2025-02-07T20:42:30Z

github-git/social-open-source.md

+:::{admonition} For maintainers
+:class: tip
+**Support contributors to feel confident and welcome**  
+Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.  


Suggested change

Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.

Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.

I don't fully understand what "that" is; does the bandwidth refer to the maintainer's time in helping the first-time contributors understand (the issue, code collaboration, GitHub etiquette)? I think it would be good to be more concrete here.

Technical: "if you don't" is duplicated in this sentence, would remove one.

Suggested change

Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.

Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth for <what exactly, helping them out?>, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them.

Update: after going through the entire file, I think this should be only in one place (and I think the location below is better suited). I'd recommend removing this admonition here and merging below.

I really appreciate the thoughtful input here, @slobentanzer and @hamogu !! thank you both. I'm working on this locally and will reply to comments once I push the changes. (i may have a few questions / thoughts to discuss too!).

@slobentanzer you may also want to peruse our entire lesson set that we've been developing here for context

The goal is that we (and others) can use them in sprints as resources for beginners and people new to the space. This lesson sets the stage for the social elements of open source. But also, social cues are added throughout all of the lessons.

We ran a review of the first few lessons already, but I plan to open a new pr so folks can review the second half of the lessons too. And of course, issues are always welcome if things are missing, off, etc! If people use these during our summer sprints, I hope we will get even more feedback on them.

Hi @lwasser, thanks, that's great. I was looking for a resource to not have to reinvent the wheel on the GitHub etiquette onboarding for all the scientists that come without much background there. I'll certainly use it and contribute back my conclusions.

For my context: what kind of contributors are you usually dealing with in these sprints? What is their level (BA, MA, PhD, other), what is their connection to science?

github-git/social-open-source.md

slobentanzer

Generally very good! Main open question for me (see also the Slack post): how do we account for the "science" part, which is a distinct flavour of open source?

Compare also here.

slobentanzer · 2025-02-10T12:36:04Z

github-git/social-open-source.md

+:::{admonition} For maintainers
+:class: tip
+**Support contributors to feel confident and welcome**  
+Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.  


I don't fully understand what "that" is; does the bandwidth refer to the maintainer's time in helping the first-time contributors understand (the issue, code collaboration, GitHub etiquette)? I think it would be good to be more concrete here.

Technical: "if you don't" is duplicated in this sentence, would remove one.

Suggested change

Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.

Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth for <what exactly, helping them out?>, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them.

github-git/social-open-source.md

slobentanzer · 2025-02-10T12:46:41Z

github-git/social-open-source.md

+
+- **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.   


Is it possible to give a rough estimate of the time frames? This may be too project-specific, but from experience I would say weeks (maybe 2 weeks)? Could also include the advice that it is good to agree with the maintainers on these time frames.

This is hard! what would you suggest? I had a pr to geopandas that was open for a year! it did get merged and it was a big pr (a full module). We've also had people from sprints work on things for months.

I do love the idea of being a bit more specific. I just am not sure how to best word this. But sometimes people just are burnt out and can't work on something they said they would. rather than going dark, i'd prefer they just say - hey - i can't work on this anymore so someone else can pick it up.

I didn't mean the contributor or maintainer should be obliged to complete the work in two weeks, rather we'd advise to give a response to any of the following results in that time frame:

positive, I'll do it soon

positive, but no time now (indicate window)

no bandwidth ATM, someone else feel free to pick up

I feel like no communication leaves everyone in a bad place; it should not be too hard to respond to requests or reminders with one of these options (are there more?). Also, I think one or two weeks for this sort of response is reasonable (except, again, if otherwise agreed on by contributor/maintainer).

slobentanzer · 2025-02-10T12:48:04Z

github-git/social-open-source.md

+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 don’t have the bandwidth to support a new contributor, acknowledge their effort and, if possible, point them to alternative resources or other beginner-friendly projects.


Seems a duplication of the admonition above. Maybe only here?

Reason: this document will probably rather be read by contributors than maintainers, so putting the maintainer admonition before the contributor section may not be the best order.

slobentanzer · 2025-02-10T12:51:17Z

github-git/social-open-source.md

+
+- **Use supportive language in issues and PRs.**  
+  - Instead of "This is wrong," try "Let's adjust this to match the project style." 
+


Suggested change

- **Credit their work.**

- In any channels that you use to disseminate the project (GitHub release notes, social media, chat communities, papers, etc.), make sure that you correctly attribute the work done by contributors.

- Tools like [allcontributors](https://allcontributors.org/) make it easy to acknowledge your contributors' efforts on your README directly.

https://output.circle-artifacts.com/output/job/9e995aaa-fe07-4654-8e9f-8ff53b2da6ff/artifacts/0/html/github-git/social-open-source.html#for-maintainers-support-document-and-acknowledge-contributors

Thank you for this!! I decided to revamp the entire maintainer's section (well, make it a section. Check out the preview above). I added all contribs and tried to make that point about acknowledging people's time clear. let me know what you think.

The other tool I personally LOVE that some don't is pre-commit.ci bot to take that linting setup out of the contributor's hands. They can lint if they want but you can call the bot to lint, too. I really love using it and have found it works well, but some people don't like pre-commit at all (you don't have to set it up). I may add it as a note - also NOTING that some don't like it.

slobentanzer · 2025-02-10T12:53:59Z

github-git/social-open-source.md

+
+This lesson covers three key aspects of open source etiquette:  
+
+**1️⃣ Engage thoughtfully in open source communities**  


This does not line up with the sections below; "trust" is 3 and "don't bite off more than you can chew" does not have a section.

slobentanzer · 2025-02-10T15:12:08Z

github-git/social-open-source.md

+:::{admonition} For maintainers
+:class: tip
+**Support contributors to feel confident and welcome**  
+Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.  


Update: after going through the entire file, I think this should be only in one place (and I think the location below is better suited). I'd recommend removing this admonition here and merging below.

lwasser · 2025-02-11T19:32:56Z

@all-contributors please add @slobentanzer for code, review

allcontributors · 2025-02-11T19:33:07Z

@lwasser

I've put up a pull request to add @slobentanzer! 🎉

lwasser · 2025-02-11T21:55:29Z

@all-contributors please add @hamogu for code,review

allcontributors · 2025-02-11T21:55:39Z

@lwasser

I've put up a pull request to add @hamogu! 🎉

lwasser · 2025-02-11T22:18:19Z

here

Thank you for acknowledging us in your guide!! I think we should add a section on getting started and highlight sprints as a powerful way to do that. We run them yearly, and all the big meetings run them too . They’ve been key in onboarding contributors in our community, yet we haven’t mentioned them in these lessons.

In terms of the science flavor, let's talk more about what you see as being specifically different in the scientific ecosystem.

It's tricky because core packages like numpy, pandas are used outside of science. Smaller domain-specific packages may have a different type of community (if a community at all!) that supports them. Let's chat more but perhaps outside of this PR!

Co-authored-by: Hans Moritz Günther <[email protected]> Co-authored-by: Sebastian Lobentanzer <[email protected]>

willingc

Overall, I like this section quite a bit. I've added a few suggestions mostly around communication.

willingc · 2025-02-13T22:08:53Z

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

+
+## 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.  


At some place in the lessons, we should state that we are using GitHub as a name to encompass social repository services which could be companies like GitLab or self-hosted Gitea instances.

willingc · 2025-02-13T22:12:46Z

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

+
+For maintainers: 
+
+* **1️⃣ Support contributors to help them feel confident and welcome** 


Suggested change

* **1️⃣ Support contributors to help them feel confident and welcome**

* **1️⃣ Support contributors by building a welcoming project**

willingc · 2025-02-13T22:13:29Z

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

+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**


Suggested change

* **2️⃣ Develop contributing documentation that outlines the types of contributions you can support**

* **2️⃣ Develop contributing documentation to guide contributors to success**

willingc · 2025-02-13T22:15:59Z

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

+
+### 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. 


Suggested change

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.

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.

willingc · 2025-02-13T22:17:51Z

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

+  - 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.  


Suggested change

- Some projects **may not be ready** for your change.

- 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.

willingc · 2025-02-13T22:30:41Z

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

+    > “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.  


Suggested change

- Maintain good communication—if a maintainer asks for changes, reply and iterate.

- 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.

willingc · 2025-02-13T22:32:42Z

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

+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.  


Suggested change

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 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."

Also, Pro tip: If a new contributor successfully merges a PR, ask if they would be interested in contributing again. It builds confidence and will often result in more contributor engagement.

willingc · 2025-02-13T22:35:54Z

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

+- **Be patient and approachable.**  
+  - GitHub can be intimidating—help create an environment where people feel comfortable asking questions.
+
+- **Give constructive, actionable feedback.**  


Suggested change

- **Give constructive, actionable feedback.**

- **Give direct, constructive, actionable feedback about the contribution content.**

willingc · 2025-02-13T22:37:44Z

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

+
+- **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.  
+


Try to add a section about what happens after a PR is submitted. Establish norms for time to receive feedback and set contributor expectations.

willingc · 2025-02-13T22:38:36Z

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

+
+## 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. 


Suggested change

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.

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, communication, technical, and even management skills.

lwasser changed the title ~~Fix social page~~ Edit: social elements of github and oss broken down Jan 31, 2025

lwasser changed the title ~~Edit: social elements of github and oss broken down~~ feat(guide): social elements of github and oss Feb 1, 2025

sneakers-the-rat reviewed Feb 1, 2025

View reviewed changes

hamogu reviewed Feb 7, 2025

View reviewed changes

slobentanzer reviewed Feb 10, 2025

View reviewed changes

allcontributors bot mentioned this pull request Feb 11, 2025

docs: add slobentanzer as a contributor for code, and review #117

Merged

allcontributors bot mentioned this pull request Feb 11, 2025

docs: add hamogu as a contributor for code, and review #118

Merged

lwasser changed the title ~~feat(guide): social elements of github and oss~~ [feb 18 merge] feat(guide): social elements of github and oss Feb 12, 2025

lwasser and others added 6 commits February 12, 2025 13:46

fix: update the social page

94bf032

fix: update the social page

03936dc

add: graphic to make the page more interesting

2655c90

Apply suggestions from code review

2c3e337

Co-authored-by: Hans Moritz Günther <[email protected]> Co-authored-by: Sebastian Lobentanzer <[email protected]>

fix: edits from review

e8fdfee

fix: update landing page and move social to the top

9f617e2

lwasser force-pushed the fix-social branch from 07e9d8b to 9f617e2 Compare February 12, 2025 20:47

willingc reviewed Feb 13, 2025

View reviewed changes

lwasser mentioned this pull request Feb 14, 2025

review: landing page for contribute to open source lessons #122

Open

lwasser added the reviews-welcome A ruby related issue (website) label Feb 15, 2025


		## 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 workplaces, GitHub interactions happen asynchronously, across time zones, and often with volunteers.

	Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.
	Many new contributors struggle with GitHub’s learning curve and imposter syndrome. If you have bandwidth, try to be sensitive to that. If you don't have bandwidth, gently nudge them to a project that might be a better fit for them if you don't.


		- Use supportive language in issues and PRs.
		- Instead of "This is wrong," try "Let's adjust this to match the project style."

+- **Credit their work.**
+  - In any channels that you use to disseminate the project (GitHub release notes, social media, chat communities, papers, etc.), make sure that you correctly attribute the work done by contributors.
+  - Tools like [allcontributors](https://allcontributors.org/) make it easy to acknowledge your contributors' efforts on your README directly.


		This lesson covers three key aspects of open source etiquette:

		1️⃣ Engage thoughtfully in open source communities


		For maintainers:

		* 1️⃣ Support contributors to help them feel confident and welcome

	* 1️⃣ Support contributors to help them feel confident and welcome
	* 1️⃣ Support contributors by building a welcoming project

	* 2️⃣ Develop contributing documentation that outlines the types of contributions you can support
	* 2️⃣ Develop contributing documentation to guide contributors to success


		### 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.

-  - Some projects **may not be ready** for your change.
+  - 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.

	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 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."

	- Give constructive, actionable feedback.
	- Give direct, constructive, actionable feedback about the contribution content.


		- 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.


		## 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.

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

Are you sure you want to change the base?

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

Conversation

lwasser commented Jan 31, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slobentanzer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slobentanzer Feb 11, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lwasser commented Feb 11, 2025

allcontributors bot commented Feb 11, 2025

lwasser commented Feb 11, 2025

allcontributors bot commented Feb 11, 2025

lwasser commented Feb 11, 2025

willingc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slobentanzer Feb 11, 2025 •

edited

Loading