The post 6 Things to Avoid When Contributing to Open-Source Projects first appeared on Qvault.
With #HacktoberFest being a thing, there has been an influx of devs desperately trying to contribute to their favorite Open-Source projects. Unfortunately, many of these pull requests have been a waste of time, with the maintainers ultimately unable to use the contributions. Maintainers don’t want to waste their time reviewing bad PRs, and contributors don’t want to waste their time writing code that will never make it into production.
Let’s take a look at some common pitfalls that developers fall prey to when working on an open-source project. As a side note, we recently open-sourced the Qvault front-end, so take a lookat that if you want to help out.
1. Pull Requests Should Handle ONE Thing
Don’t open a PR like this:
- Fixes bug #543
- Adds new linting rules
- Includes feature #456
Your PR should do one thing. Small diffs decrease the cognitive load of the reviewer and make it easier to get your code into the main branch. If you have beef with multiple issues in a project then open multiple PRs.
2. Don’t Break Consistency
This one happens the most often to me in my own projects. Well-intentioned developers open pull requests with any of the following annoyances:
- Omitting semicolons in a project that prefers them
- Using spaces in a project that has clearly been using tabs
- Introducing snake_case in a camelCase repo
When you contribute to an existing project, use the existing styling. No one gives two hoots about your preference on the “tabs vs spaces” debate in the context of this pull request.
If you think styling needs to change, see points #1 and #3.
3. Don’t Start Work Without Approval
If you hop into a Github repo and find something you don’t like, don’t immediately open a pull request. Follow these steps instead:
- Is there already an issue logged? If not, make one.
- If there is an issue, reach out to the maintainers (just comment on the issue) and let them know you want to work on it, and give a quick overview of how you will address it.
- Assuming you have their blessing, start work on your PR.
This will help mitigate the creation of pointless PRs that will never be accepted on the basis of a flawed premise.
4. Don’t Re-open Known Problems/Solutions
Some codebases have thousands of open issues, take the Go language project, or the nocode repository as an example. No one wants to read your duplicate issue or review your duplicate pull request. Make sure there isn’t an existing open or closed issue for what you are trying to address.
5. Squash Those Commits
Not every project will require (or care) about commit squashing. That said, there are no projects that require not squashing commits. To be on the safe side just give ’em a squash.
6. Be Meaningful
Rewording documentation and other frivolous changes make you look like these assholes. This particularly atrocious example is not only scoped to pointless documentation changes but actually makes the documentation worse.
Top comments (2)
Nice post!
I have some questions though.
1. I think this kind of PR is perfectly OK
If I can't open PR like this one, then what else can I open? (other than typo fix and trivial fix)
2. What is commit squashing?
In relation to #1, the "fixes bug #543" part was one of 3 messages in the example PR. By itself it's fine. When added with the other 2 at the same time, it makes things difficult.
Commit squashing makes multiple commits which form part of the PR (so allowing you to work incrementally and commit often) show as only 1 commit on the receiving branch. It helps keep things tidy and concise.