Thursday, April 15, 2021

A guide on successful open source collaboration

You are sharing your source with others or you want to contribute to an open-source project? This is great!

Let's talk about a few points to ensure this will be an enjoyable experience for everyone.

Setting things up

First things first: If you maintain a git repository please add an appropriate .gitignore and a .gitattributes file.

There are several templates for that and articles explaining them - hence I am not going into detail here. Just one thing: rule those line endings and don't let them rule you by messing up your blue dots in the IDE, garbling your class completion or your project file, or making every second commit a complete mess.

People have different settings in their git on how to deal with line endings and there is no "correct" or "wrong" way, they are just different - that's why smart people invented the .gitattributes file to let the repository decide how line endings should be treated equally for every participant. Add it, possibly clean up any existing wrong line endings and everyone will be happy going forward.

Know the tools

Please learn the tools you are using - if your history looks like Cthulhus tentacles because you don't know how to properly pull rebase you are doing something wrong. This is especially important when you are creating pull/merge requests and the reviewer asks you to fix some things and get the branch up to date for a clean and conflict-free merge. Learn how to interactive rebase and respect the maintainers time by not having them look through your trial and error going back and forth, turning things upside down three times, merging upstream changes in the middle garnished with "fixed conflicts after merge" commits until you finally reached the state you want to submit. Learn how to work with different remotes managing your fork and the original repo in order to keep your fork up to date in a clean way. Again there are guides out there explaining these things in great detail. Please read them.

Respect each other

Divide separate things into own commits, write meaningful commit messages, and if necessary put things into separate pull requests to not throw one big clump at the maintainer making it easier to look through the several things piece by piece. It will also make it easier to address remarks made during the review, produce a better and/or quicker outcome and leave all participants in a good mood.

Stick to the coding style of the maintainer - this includes naming and formatting as well as the usual approach on things in the repository. The codebase uses begin after then instead of in a new line? Then do so as well. They write integer lowercase or String uppercase? Then do so as well. Don't try to sneak your personal style in there if it's in contrast to the existing code. Nothing worse than a patchwork of different coding styles emerging over time the more contributors come together.

These are just some of my recommendations and you might have a different opinion on some things or some details but after being active in open source development for over 15 years I believe following these suggestions will improve collaboration on open source projects for everyone.

If you are not contributing to some open source project yet - then please be encouraged to consider doing so. Start small, maybe you found an issue in some library you are using - find out of it's known yet and report if not. If you already found a fix, consider providing this fix attached to the issue or as a pull/merge request.

No comments:

Post a Comment