As I maintain several FOSS projects, I figured it would be convenient to have in a central place some concise guidance on contributing.
Here are, as concisively and actionable as possible, the rules regarding interactions and contributions on the projects I maintain on GitHub.
- You're Welcome
- The basics
- Don't contact me privately
- Communication Channels
- It's OK to ping me again
- Discuss before implementing
- Check tests
- Typos and grammar
- It's OK to make errors
- I maintain control
I make FOSS for people to enjoy. Of course you're welcome to come and interact!
But there should be no barrier here, it's OK to come ask on the chat if you don't understand.
Don't contact me privately
This is an open project. It's never OK to contact the maintainer privately.
You may, very rarely, need to privately provide sensible data, but the discussion must be kept to a public place, so that people with knowldge may answer and so that it may help other people later.
There are exactly 2 convenient places for a discussion: the Miaou chat and the issues of the specific project you're interested into.
When you don't get an immediate answer, come back later, there will be one.
In case of doubt, always come to this chat server. If necessary, ask for me (
The project you want to discuss probably links to a specific room but you're welcome too in the general programmer chat room, Code & Croissants. Yes, most messages are in French but people are kind and will answer you when you speak in English.
You're probably used to GitHub issues if you decide to go there first. I'm not fan of template, there's no specific rules, just don't forget to provide the context (purpose, version, OS, log file, arguments, etc.).
It's OK to ping me again
I maintain a lot of projects and I have a small head.
So, if you think I may have missed or forgotten a point, make you heard again.
Discuss before implementing
Rather than taking the risk of building something which doesn't fit the project's vision, or which will conflict with a change in progress, you'd better come to the chat and discuss your ideas, even if you're not sure you'll do the work.
Don't change more files than necessary. Keep your PR focused.
If there's a test solution on this project, run it and ensure tests pass before doing a pull request.
Don't open a PR with just formatting. I know how to use formatting and lint tools; such a PR is only a nuisance.
Don't format files which aren't relevant to your change.
If there's a format script or format configuration file in the project, run it before doing a PR.
Typos and grammar
My English isn't great, corrections are welcome.
If it's subjective and about style, it should probably be a suggestion on the chat rather than a PR, though.
It's OK to make errors
Everybody make errors, and sometimes very dumb ones. It's OK: we'll fix them, and move on. It's better to say something stupid and be corrected than to keep dumb ideas.
I maintain control
The biggest lesson you learn when maintaining FOSS is that you shouldn't merge something when not really sure it fits the project and codebase.
I'm still paying the cost of merging years ago some PR whose implementation didn't really convince me but which looked important. If I don't like some feature, I really should not merge it in.
So, I'll sometimes be deliberately slow to avoid making this error. Even if your contribution has a good probability of being awesome, even if you know the topic much better than me, I may need a lot of time to understand and maybe I'll initially just take notes.