Open Source Contribution Etiquette(tirania.org)
tirania.org
Open Source Contribution Etiquette
http://tirania.org/blog/archive/2010/Dec-31.html
7 comments
Wow, I had never heard of someone doing major reformatting, reorganizing, or refactoring on someone else's code before submitting a patch! I would say that anyone who would do such a thing doesn't understand what it means to work with other people!
It happens although I'd like to believe it's rare. I perpetrated the most glaring example of patch refactoring I've ever seen.
The scenario: - Original maintainer's module code totally ignored the code style conventions for the larger project it was a part of. - Module maintainer had been dragging heels on a raft of bugfixes, module stuck in beta limbo for six months. - Boss says we need this feature (cleaned up and stable) in our codebase by the end of the month.
My play: I refactored the codebase to meet larger project coding style standards, patched every bug in the issue queue, added a suite of unit tests and submitted the entire thing back to the maintainer.
Maintainer's play: The maintainer opted to reject my patch on the grounds he preferred his personal coding style to the project standards.
Endgame: I promptly re-rolled the patch as an addition to another related module, got the code committed to that project, posted an issue to the original maintainer's queue indicating his module was deprecated. Last time I checked in dude's module was still buggy and he was taking flack from several people involved with the larger project for being a cowboy with the coding standards.
The scenario: - Original maintainer's module code totally ignored the code style conventions for the larger project it was a part of. - Module maintainer had been dragging heels on a raft of bugfixes, module stuck in beta limbo for six months. - Boss says we need this feature (cleaned up and stable) in our codebase by the end of the month.
My play: I refactored the codebase to meet larger project coding style standards, patched every bug in the issue queue, added a suite of unit tests and submitted the entire thing back to the maintainer.
Maintainer's play: The maintainer opted to reject my patch on the grounds he preferred his personal coding style to the project standards.
Endgame: I promptly re-rolled the patch as an addition to another related module, got the code committed to that project, posted an issue to the original maintainer's queue indicating his module was deprecated. Last time I checked in dude's module was still buggy and he was taking flack from several people involved with the larger project for being a cowboy with the coding standards.
Yea neither have I, that's crazy. I try to make my patches as small as possible (makes it easier to merge as well)
Yeah, I'm not denying it happens, but it seems like common sense to me. The type of programmer inclined to refactor and rename should be the first to recognize the value of uniform coding conventions within a project.
I've always thought a general etiquette guide and howto for contributing to open source projects would be useful.
Hmm,
"The maintainer is in for the long-haul, and has been working on this code for longer than you have. Chances are, he will keep doing this even after you have long moved into your next project."
That might be a common pattern but it seems like it's sort-of a dead end pattern. If put yourself out there as The Maintainer in that way, you've basically said no is going to be able to make major contributions without you - going it alone become a self-perpetuating process and it's indeed not surprising that no one will stick around.
I have a large project that I hope to release in the next 1-3 months. I've put a large amount of effort into it. I'm also putting effort into making the code good enough that others can come on board and make significant extensions to it. Following the existing code style certainly but quite possible rearranging functionality, breaking up and rearranging function if it's useful and so-forth.
A VCS like git that lets everyone have the branch they like can be good here. Do what you love and inclusion in the main branch should follow sooner or later...
"The maintainer is in for the long-haul, and has been working on this code for longer than you have. Chances are, he will keep doing this even after you have long moved into your next project."
That might be a common pattern but it seems like it's sort-of a dead end pattern. If put yourself out there as The Maintainer in that way, you've basically said no is going to be able to make major contributions without you - going it alone become a self-perpetuating process and it's indeed not surprising that no one will stick around.
I have a large project that I hope to release in the next 1-3 months. I've put a large amount of effort into it. I'm also putting effort into making the code good enough that others can come on board and make significant extensions to it. Following the existing code style certainly but quite possible rearranging functionality, breaking up and rearranging function if it's useful and so-forth.
A VCS like git that lets everyone have the branch they like can be good here. Do what you love and inclusion in the main branch should follow sooner or later...
It depends. If you are the main author of a large project, and you look forward to extend it by taking contributions in a direction that carries any meaning to you, integrating code at random won't magically result in a better project.
As the author an maintainer of several small FOSS projects, I rarely receive pull requests that I can merge right away. In that sense, a distributed VCS doesn't really improve over the patch-by-mail approach for random contributions (it does helps cooperation among regulars however).
I can also tell you right away that a FOSS project without direction or maintainer quickly dies, independently of the VCS. Successfull forks are very rare. Mostly, projects with good potential but no maintainer get simply dumped and reimplemented by another programmer.
If you are a maintainer, you will appreciate all the points the authors is making. If you are making a contribution, adhering to all the points will increase the odds of your change to make it quickly and improve the software.
Also, conversely as a contributor, I don't spend time on projects which have no maintainer or lack direction anymore. Having the source of a project (especially large) sounds useful at first, until you realize that maintaining it without the inner knowledge is a daunting task. It only makes sense if you are willing to use it extensively (and become the new the-facto maintainer).
As the author an maintainer of several small FOSS projects, I rarely receive pull requests that I can merge right away. In that sense, a distributed VCS doesn't really improve over the patch-by-mail approach for random contributions (it does helps cooperation among regulars however).
I can also tell you right away that a FOSS project without direction or maintainer quickly dies, independently of the VCS. Successfull forks are very rare. Mostly, projects with good potential but no maintainer get simply dumped and reimplemented by another programmer.
If you are a maintainer, you will appreciate all the points the authors is making. If you are making a contribution, adhering to all the points will increase the odds of your change to make it quickly and improve the software.
Also, conversely as a contributor, I don't spend time on projects which have no maintainer or lack direction anymore. Having the source of a project (especially large) sounds useful at first, until you realize that maintaining it without the inner knowledge is a daunting task. It only makes sense if you are willing to use it extensively (and become the new the-facto maintainer).
I'm mostly saying that it seems useful for a maintainer to offer those aiming to contribute a path towards doing more than just fixing bugs.
There's no need for that. Users/contributors will do whatever they want with the source already. That includes hacking the source for private purposes only. Github is the pinnacle of that attitude (which in my opinion is not social coding at all -- but I digress).
Of course, the articles misses an important point: talking to the maintainer/author first. If you were about to do a big change, would you know if there were any chance to be integrated first? Maybe knowing if someone is already working on it? (heavy refactoring comes to mind). I've gained precious insights about design by simply talking to authors before starting to work on a contribution, saving my time countless times.
If your intention is doing a change no matter what, then you're not really interested in _contributing_.
Of course, the articles misses an important point: talking to the maintainer/author first. If you were about to do a big change, would you know if there were any chance to be integrated first? Maybe knowing if someone is already working on it? (heavy refactoring comes to mind). I've gained precious insights about design by simply talking to authors before starting to work on a contribution, saving my time countless times.
If your intention is doing a change no matter what, then you're not really interested in _contributing_.
SCM (a la GitHub pull requests) really helps with this. When your contribution is reduced to a line-by-line diff, it becomes clear what the essential changes are (and satisfying to make the diff as short as possible).
Who does that ? Each time i had to fix something in a OSS project i touched as little code as possible. Everybody knows is no fun working with code written by somebody else.
Indeed, the code formatting style used by Mono (eg spaces before argument parens like "SomeMethod ()") is one of the biggest reasons I'll probably never contribute to it. I can't change the existing style, but it makes my eyes bleed to read, so I avoid it.
Maybe it would be a good idea not only to have coding standards, but also automatic handling of auto-formatting code when checking in. If you have a highly flexible coding style system like uncrustify for example, and check ins would be guaranteed to be automatically formatted, you could simply tell vim or emacs to format it with your coding style when opening, and then auto-format it for check in..
I know it's oversimplifying, but maybe it would help some people.
It helps to keep clear the distinction to "contributing to someone's open source project" and "writing code for an open source project".
The code might be open/free, but the maintainer of a given instance/repo is ultimately in charge of at least that.
The code might be open/free, but the maintainer of a given instance/repo is ultimately in charge of at least that.