Table of Contents
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
I make FOSS for people to enjoy. Of course you're welcome to come and interact!
The basics
If you're new to contributing to FOSS, you may want to learn about how to contribute and how to use GitHub.
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
Seriously.
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 knowledge may answer and so that it may help other people later.
Don't push LLM-generated PRs
I'm not paid to maintain those open-source projects. I don't want to waste my time triaging and interpreting LLM-generated texts. I don't want to try educate an LLM in my comments and review.
You may think such PR is easier to handle because it looks more refined, but it mostly takes more energy to read. Even when I end up merging it, or doing the work myself, after having been dragged into your concern, it wasted too much time which is detrimental to other projects.
You may use an LLM to diagnose, understand, find solutions, whatever, but don't create with it on my projects, and don't paste its analysis.
An issue without solution is better than a LLM generated PR.
Communication Channels
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.
Miaou
In case of doubt, always come to this chat server. If necessary, ask for me (@dystroy).
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.
GitHub issues
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
Cold pull requests are painful to deal with.
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.
By discussing, we also often design better solution.
I fight complexity
Especially user-facing complexity and dependency related complexity.
Sometimes you add a new feature, which makes sense, but I won't merge your code because it adds a launch argument, or something in the visual space, or a dependency, or a configuration item.
It looks like nothing but this complexity adds up and leads to applications that are a nightmare to understand and maintain.
Scope
Don't change more files than necessary. Keep your PR focused.
Check tests
If there's a test solution on this project, run it and ensure tests pass before doing a pull request.
Formatting
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.