Meera still remembers the exact wording of the comment on her first pull request. It was polite, two lines long, and it broke her heart a little. “Thanks for this! Could you please read our contribution guidelines and resubmit?” She had spent a whole weekend fixing a small bug in a popular content management plugin, and the maintainers had not even looked at the fix. They had looked at everything around it.
This is a story about that rejection and the checklist Meera built afterwards. If you work with a CMS, whether as a developer, an agency owner or a keen hobbyist, you will probably one day want to contribute a fix, a translation or a documentation tweak to an open project. The most useful thing to do first is the least glamorous: read the guidelines.
What went wrong with the first pull request
Her patch was fine. The trouble was everything the project had asked for in a short file in the repository root. It wanted a discussion in the issue tracker before any code arrived, so maintainers could say whether the change was wanted. It wanted commits in a specific message format. It required tests for any behaviour change and a changelog line. And it asked contributors to branch from a development branch, not the main one. Meera had broken all four.
None of the rules was unreasonable. Each one saved the maintainers time and kept a small volunteer team from drowning in contributions. She only learned about them because someone took the trouble to point at the file. A more impatient reviewer might simply have closed the request, and people do get closed on without ceremony.
The checklist she built
Meera turned the experience into a one-page list she now uses before touching any project. Here it is, in the order she follows it.
- Find the guidelines file. Look for a contributing document, a code of conduct and a security policy. If you cannot find them, check the project’s website and its discussion forum.
- Read the code of conduct first. It tells you how people are expected to speak to each other, which matters more than syntax.
- Look for the “before you start” section. Many projects want an issue or a conversation first. Do that before writing code.
- Check the branching and commit rules. Which branch to start from, how to name yours, and how to word commits.
- Note the testing and style requirements. Linters, test suites and coding standards are often enforced automatically, so failing them is an instant red mark.
- Look for documentation and changelog expectations. Some projects will not merge code without a matching note.
- Understand the licence and sign-off rules. Some projects ask contributors to confirm they have the right to submit the work.
- Find out who reviews and how long it usually takes. Patience is easier when you know the rhythm.
The point of the list is not bureaucracy. Each item answers one of three questions that apply everywhere: what is allowed, what is not, and who decides.
Why projects write these rules down
Meera got curious and asked one of the maintainers, Tomas, why the guidelines were so detailed. He laughed and said every line was a scar. The commit message format existed because a release manager once spent a night rebuilding a changelog by hand. The “discuss first” rule existed because a contributor had delivered a huge feature nobody wanted and was understandably hurt when it was declined.
That story changed how she saw house rules. They were not a wall around the project, but a map left by people who had already walked the path. Ignoring it was not bravery, only a way of repeating someone else’s mistakes.
The same logic applies to the sites you build
Agencies run into the same thing from the other side. A client’s website is a place with rules too, about page structure, tone, legal pages and who may publish. Before development starts, it pays to write those expectations down, as our guide to the groundwork a company site needs before developers write a line suggests. And when you decide which sections the finished site needs, the rundown of pages every company website should carry doubles as a rulebook for what visitors expect.
The resubmitted request
Meera closed her first request, opened an issue as the guidelines instructed, waited for a maintainer to say yes, then rebuilt her fix on the right branch with tests and a tidy commit. It was merged in two days. The patch was identical in substance. The only thing that changed was that she had finally read the page the project asked every newcomer to read.
She also realised she had been making the same mistake in other places. When she started writing about her plugin experiments, she posted on whichever site came to mind and was mildly surprised when one piece was removed for breaking a rule she had never opened. Since then she has used a directory of free publishing platforms named FreePostFinder to browse options, and she takes its reminder to follow each platform’s own community rules as her cue to read the rules first.
What to do when the guidelines are thin
Some smaller projects have no contributing file at all. In that case Meera reads the last handful of merged requests and the discussion beneath them. They show the unwritten conventions: how long descriptions run, whether maintainers like screenshots, how quickly people reply. Then she opens an issue that simply asks, “Is a patch for this welcome, and is there anything I should know first?” Maintainers nearly always answer kindly, and the question itself signals respect. It is never wasted effort, even when the answer is a plain no.
Turn it into an audit of your own habits
Here is a short audit you can run this week. Choose three places where you contribute, publish or collaborate: a code repository, a forum, a platform for your articles. For each one, answer these questions in writing.
- Have I actually read the rules, or only clicked agree?
- Can I say in one sentence what is allowed and what is banned?
- Do I know who enforces them and what the first consequence is?
- When were the rules last updated, and have I reread them since?
- Is there anything I am doing that I suspect the rules would not like?
Be honest with the last question. Most people find one answer that makes them wince, and that wince is the whole value of the exercise. Fix it now, calmly, rather than later in public.
Meera’s guidelines habit has become a small tradition on her team. New hires get a short document listing the rules of every project and platform the agency touches, with a note on who to ask. It takes an afternoon to compile and saves countless polite, heartbreaking comments.
