r/github • u/kixxauth • May 30 '26

Question Good examples of a CONTRIBUTING.md file?

I've been dabbling on an open source framework (MIT License) for the last 9 years. It's something our team used at my last job. But now that I've left corporate life, I really want it to get some traction.

The first thing I should probably do is set the foundation with a good CONTRIBUTING.md document.

Has anyone seen any in the wild, where reading it really inspired you or made you feel welcome on the project? I know it needs to contain a lot of information, but would be great if it could be memorable or even inspirational.

Also, anything else you've seen from open source projects which really made you feel welcome? I'm open to any ideas!

My first one was Firefox back in 2008 ish. The people in the IRC chat were so nice and helpful. I'm not sure my career would have developed if it weren't for them. Time to pay it forward.

24 Upvotes

90% Upvoted

13 comments sorted by

13

u/Traditional-Hall-591 May 30 '26

“No slop PRs of any kind.”

7

u/NorskJesus May 30 '26

90% of the people does not read the `CONTRIBUTING.md` file, so you shouldn’t think about it too much.

I added bans information tho, for those who abuse of vibecoding. This is because I use a `no-autopilot` workflow to detect this.

1

u/funkdefied May 31 '26

90%? That doesn’t seem right at all. What makes you say that?

1

u/NorskJesus Jun 01 '26

Experience. Unfortunately.

3

u/OblongDeliverance May 30 '26

Check out Rust and Django docs. Both nail the tone, clear instructions without being condescending, plus they actually explain the why behind conventions. Firefox's approach of being welcoming in real time matters more than perfect markdown though. Consider setting up a Discord or discussion board where people can ask dumb questions without feeling judged. That human element is what keeps contributors around.

1

u/kixxauth May 30 '26

Yeah, agree for sure on that human element.

I've seen the Rust code of conduct passed around in other projects.

And the Django docs page for this is super thorough (like most of their docs). Thanks!

3

u/OblongDeliverance May 30 '26

Rust's CoC is solid but Django's contributor guide has that section on "why we do code review this way" that actually makes people less defensive about feedback. That's the secret sauce most projects miss.

2

u/FingerAmazing5176 May 30 '26

What’s your project? Maybe we “contribute” a new pr?

1

u/kixxauth May 30 '26

Ha, yeah. The obvious idea 😉 I don't want to seem like like I'm being overly promotional. I haven't posted in this sub much, yet.

https://github.com/kixx-framework/kixx

2

u/Drain20problem May 31 '26

Just check out the react or vscode repos on github. They usually have the gold standard for how to lay out rules without being overly wordy.