Back to Explore
GuideVibeFix editorialUpdated Nov 13, 2026

Stop Losing Good Contributions to a Blank Text Box: Issue/PR Templates and CONTRIBUTING for Your Vibe Project

Good contributors are lost to blank text boxes and missing details, not to a lack of goodwill. This guide shows how to build issue forms, PR templates, and CONTRIBUTING.md so the first submission is reviewable. All example projects, people, and numbers in this guide are fictional.

Five developers collaborating around a desk, discussing code shown on several monitors

Your vibe project is open source. In week one it gets 3 stars. In month two someone files the first issue: "This feature doesn't work well." You open it and find a four-word title and an empty body. Which feature? What goes wrong? On what device? You ask two follow-up questions and never hear from the person again. In month three someone files the first pull request: 40 files changed, more than 2,000 lines, no description, no tests, no linked issue. You spend an evening reading the code and finally close it, feeling guilty about it. The problem is not that nobody wants to help. It is that the road to helping is too hard: the contribution entry is a blank text box, contributors do not know what you want, and you do not know what they are handing you.

Two things to make clear first. First, the walkthrough project "Pinecone Notes", the maintainer "A-Song", the contributor "Xiao Bei", and every time and quantity in this guide are fictional, invented only to explain the process. Second, boundaries: this site already published a guide on contributor onboarding for AI-generated repositories, which covers how newcomers enter a repository, get it running, and make their first contribution; a guide on open-source repository operations after the first stars, which covers operations including the issue triage pipeline; and guides on open-source release and licence choice. This guide repeats none of them. It covers one thing only: the entry to the contribution funnel — issue templates, pull request templates, and CONTRIBUTING.md — so that everyone who wants to help hands you something usable on the first try.

Five developers collaborating around a desk, discussing code shown on several monitors

1. Look at the funnel first: where helpers drop out

Before designing templates, draw the road a contribution travels. From "I want to suggest something" to "merged into the main line" there are five steps: opening the template chooser, submitting an issue or PR, having enough information to review, entering review, and merging. Every step leaks: step one leaks on "should I file an issue or open a PR directly"; step two leaks on "the blank text box gives me no idea what to write"; step three leaks on "no reproduction steps, no version number, the maintainer cannot reproduce it"; step four leaks on "the PR is too big for a reviewer to read"; step five leaks on "the review sat untouched for two weeks and the contributor left".

The fictional example funnel numbers in this guide are: 100 people open the template chooser, 70 submit an issue or PR, 45 arrive with enough information to review, 20 enter review, and 12 are finally merged. These numbers are fictional, and they make one point: templates and CONTRIBUTING improve the conversion of the first three steps, not the merge rate of the last one — they get more people from "wanting to help" to "handing in something reviewable". If you only watch how many PRs get merged, you will wrongly conclude the problem is review; in fact most contributions die at steps two and three, in blank text boxes and missing information.

So the first rule of template design is: a template is the art of asking questions, not a fill-in-the-blanks marathon. A good template only asks for what a review must know. Every extra field loses another batch of contributors halfway through. A bug report asks for reproduction steps, version, expected and actual behaviour. A feature request asks for the problem, the proposal, and the alternatives. A question asks for background, what was already tried, and where things got stuck. Once you have asked, stop — do not add "just in case" fields like OS version, browser version, network conditions, and time zone. When the maintainer genuinely needs them, they can ask in a comment.

2. Issue templates: bug form, feature request, question triage

GitHub offers two kinds of issue template: Markdown templates and YAML forms. A Markdown template pre-fills the text box with headings that a contributor can delete at will; a YAML form renders as a real form with fields, and some fields can be required so the issue cannot be submitted until they are filled in. GitHub's official documentation, verified in November 2026, states: form files live in the repository's .github/ISSUE_TEMPLATE directory and begin with the three keys name, description, and body; after submission, the answers are converted to Markdown and appended to the issue body; and pull requests do not support forms — only Markdown templates.

A bug report form is best arranged like this (the field names are examples you can copy structurally): start with a short Markdown welcome that says "please search for duplicate issues first"; then a required textarea, "What happened?", with the hint "paste the exact error message"; a required textarea, "Steps to reproduce", with a placeholder reading "1. Open... 2. Click... 3. See..."; a required input, "Version", prompting for a release number or commit hash; and two required textareas, "Expected result" and "Actual result", kept as separate fields rather than merged into one "problem description" — when merged, people usually write only half of it. At the top level, add title: "[Bug]: " and labels: [bug, needs-triage], so a new issue is created already carrying the title prefix and the needs-triage label, and the maintainer can classify it at a glance from the list.

A feature request form must fix a different bad habit: jumping straight to a solution without stating the problem. Behind "add a dark mode" with no "why", the maintainer cannot judge whether the request is worth doing, or choose between option A and option B. So the field order for a feature request should be: first "What problem are you trying to solve?", then "What solution do you propose?", and finally "What alternatives have you considered?" All three fields are required, but each hint must state the standard: the "problem" should say who, in what situation, ran into what difficulty; the "proposal" should say concretely what would change; the "alternatives" can be a single sentence like "haven't thought about it" — the point is to make the contributor think it through once, rather than handing in a design document as the opening move.

Questions need their own separate triage, not the bug report template. A question template needs only three things: background, what has already been tried, and where things got stuck. More importantly, the template chooser should link to "ask in Discussions": many questions are usage questions that do not deserve to sit in the issue list for months. GitHub's documentation states explicitly that Discussions support YAML forms only, not Markdown templates. Good triage leaves the issue list holding only work that genuinely needs fixing or building, and the maintainer's mood improves every morning when they open that list.

Finally, one switch in config.yml: blank_issues_enabled: false. Turning off blank issues means contributors must pick a template before they can submit. For a project just starting with templates, leave blank issues on for two weeks first and watch what people submit without a template: if it is all new types the templates do not cover, the templates are missing a kind; if it is all "I didn't know how to fill this in", the hints need rewriting. Only turn blank issues off after those two weeks — and before you do, confirm the three templates (bug, feature request, question) are all in place, or you will have welded the contribution door shut.

3. The PR template: help a reviewer understand a change in five minutes

Pull requests do not support YAML forms, only Markdown templates, stored at .github/pull_request_template.md (a single template) or in the .github/PULL_REQUEST_TEMPLATE/ directory (several templates to choose from). A PR template has a single goal: let a reviewer decide within five minutes whether the change can be merged. Six fixed sections are recommended: what changed, why it changed, how it was tested, screenshots or recordings, the linked issue, and a checklist. Write the hints as HTML comments (<!-- ... -->) — they guide the person filling in the form but do not appear in the submitted text.

"What changed" should describe the change at file level, not empty phrases like "optimised the code". "Why it changed" should link to an issue number or the requirement background — without a linked issue, the reviewer must first spend half an hour guessing the motive. "How it was tested" needs concrete commands and results, such as "ran pnpm test, 12 tests passed" or "verified manually in three steps: ...", not just a ticked "I have tested this". "Screenshots or recordings" are required only for interface changes; backend changes can say "no interface change". The "checklist" needs only four to six items: tests pass, documentation updated, no breaking changes, lint run. Beyond eight items, contributors start ticking everything blindly and the checklist stops meaning anything.

Beyond the template itself, set a "small PR" rule: the fictional example number in this guide is that a single PR should change no more than 300 lines. Past 300 lines, reviewers put the PR down halfway through, and a two-week delay becomes normal. What about the excess? Split it: first a PR that only changes the data structure, then one that only changes the interface, with the dependency written in the description. Maintainers can also state in CONTRIBUTING: "PRs over 300 lines should start with an issue discussing how to split them" — stopping big PRs before submission, rather than arguing after they cannot be merged.

Draft PRs are another useful tool: when the change is not finished yet and you want the maintainer to check whether the direction is right, open a draft PR, which is automatically marked WIP in the title. Many newcomers do not know draft PRs exist; they dare not submit halfway through, and only discover the direction was wrong after finishing. Tell them in CONTRIBUTING in one sentence: "If the direction is uncertain, open a draft PR to discuss it first — don't wait until it's finished." That sentence saves more rework than any template.

4. CONTRIBUTING.md: eight paragraphs, written once

CONTRIBUTING.md is the repository's "new employee handbook", placed at the repository root or in the .github/ directory. The first version does not need to be perfect — eight paragraphs are enough: quick start, development workflow, branch naming, commit messages, testing requirements, code style, code of conduct, and release notes. The quick start should reach the point where "copy and paste three commands and it runs", with concrete commands and expected output rather than vague phrases like "install dependencies". The workflow should say "open an issue to discuss first, then fork, then open a PR" — do not assume contributors know your process. Branch naming needs one example, such as feat/xxx or fix/xxx, not just "please use meaningful branch names".

Commit messages need only a minimal convention: start with a verb, say what changed in one sentence, and reference the issue number, for example "Fix the login button overflowing on narrow screens (#123)". Do not roll out the full Conventional Commits specification with commitlint enforcement at the start — for a vibe project, a low barrier matters more than a strict convention; get contributors submitting first, then tighten gradually. Testing requirements should state clearly "which changes must bring tests": a bug fix brings a reproduction test, a new feature brings matching unit tests, a copy change needs none. Code style needs only the three most important rules: the formatting tool and command, naming habits, and no stray console.log. For the code of conduct, reference the Contributor Covenant with one sentence and a link — do not copy the full text, because the official text has a canonical version and a copied one goes stale on updates.

The release paragraph is the one most CONTRIBUTING files miss: who releases, how often, and how version numbers grow. Even a single sentence — "The maintainer releases once a month; a merged PR is not published immediately" — prevents many "my PR was merged, why isn't it live yet?" questions. Once written, link CONTRIBUTING prominently from the README, and add "I have read CONTRIBUTING" to the PR template checklist — entry points, templates, and documentation interlocking in three places is what truly closes the funnel.

5. Labels: agree on meanings before automating

Issues submitted through templates still need to pass through labels. More labels are not better — a minimal set of 8 is recommended: bug, enhancement, documentation, question, needs-triage, needs-info, good first issue, and help wanted. Give each label one sentence of meaning and write it into CONTRIBUTING: needs-triage means "nobody has looked at this yet", needs-info means "waiting for the reporter to add information", good first issue means "newcomer-friendly with clear acceptance criteria", and help wanted means "the maintainer wants this done but has no time — please take it". Labels with unclear meanings are worse than no labels at all — the same person labels something a bug today and an enhancement tomorrow, and eventually the list cannot be filtered at all.

The good first issue label deserves the most care. Three rules govern picking them: the change is small in scope, the acceptance criteria are explicit, and it does not require understanding the whole system architecture. "Change the login button text from 'Submit' to 'Log in'" is a good first issue; "refactor the auth module" is not, however simple it looks. After labelling, the fictional example number in this guide is that the issue is claimed by a newcomer within 7 days — the number is fictional, and the point is not the 7 days but that "a labelled issue must be looked after": review the good first issue list weekly, and anything unclaimed for more than two weeks is either too hard or too poorly described — remove the label and rewrite it, instead of letting it rot in the list.

Labels and templates should work together: the bug form automatically applies bug and needs-triage, the feature request form applies enhancement and needs-triage, and the question template applies question. These three automatic labels are configured in the YAML form's top-level labels key, which the official documentation confirms is supported. Automatic labelling saves the maintainer's daily manual sorting time, but it also demands one thing: label meanings must be agreed on first, or automation will simply mass-produce confusion.

6. Auto-triage and bots: a minimal setup, no over-automation

With templates and labels in place, bots can take over three small jobs: automatic labelling, the automatic first reply, and expiry reminders. Automatic labelling was covered above. The automatic first reply means: when a new issue is created, a bot comments "Thanks for filing this! A maintainer will reply within 3 working days" (a fictional example number), along with a link to the relevant CONTRIBUTING paragraph. Its purpose is to tell the contributor "someone received this", rather than leaving them in silence. But note: the automatic reply can only ever be the first sentence, never the second — after the bot replies, a maintainer must reply in person within the promised time, or the automatic reply becomes an empty promise.

Expiry reminders use a stale rule: the fictional example numbers in this guide are that an issue with no activity for 30 days is automatically labelled stale, and if nobody responds for another 14 days it is closed automatically. The stale rule needs two human sentences: when labelling stale, comment "This issue has had no activity for 30 days — please comment if it still needs attention"; when closing, comment "Closed for prolonged inactivity — please comment to reopen". Never close silently — a silent close tells the contributor "we threw your work away and couldn't be bothered to say so". Also, stale should never touch three kinds of issue: those labelled good first issue, those labelled help wanted, and bugs with clear reproduction steps — closing those costs more than keeping them.

Over-automation is the most common pitfall at this step. Some projects configure six bots: auto-labelling, auto-assignment, auto-closing duplicates, auto-nagging reviewers, auto weekly reports, and auto-scoring PRs — and the maintainer then spends half an hour every day dealing with comments the bots left. Remember one line: bots should only do things that are mechanical and cannot go wrong — labelling, sending reminders, posting links. Judgements that require understanding, such as "is this a duplicate?" or "can this PR be merged?", always stay with people. Automation exists to save time, not to look professional.

7. From submission to merge: the review checklist and thanks

By the review stage, the templates have done their job, and the rest is human work. The review checklist should have five fixed items: does the change match what the issue agreed, do the tests cover the change, is the documentation updated alongside, are there any breaking changes, and is the code style consistent? Each item should leave a trace on the PR page: when approving, the reviewer writes "checked the tests — they cover the new branch", not just a green tick. The trace matters because three months later, when someone asks "why was this change written this way?", the answer can be found on the PR page instead of in chat history.

For vibe projects, squash merging is recommended: one PR becomes one commit, the main-line history stays clean, and a rollback means reverting a single commit. After merging, do not close the issue immediately: first confirm the change is verified live, then let a bot or the maintainer close the linked issue with a comment stating "shipped in v0.4.2" (a fictional example version). Only when the contributor receives that notice has the full journey been completed — many people file a PR and never look back, because the last time their work was merged into silence and they never learned whether it shipped.

The last thing easily missed is thanks. When merging a PR, @-mention the contributor with a thank-you in the comment, and add their name to the README contributor list or the release notes. It costs almost nothing and is the best retention tool there is. Open-source contributors are not employees; there is no salary. Only two things keep them: their work actually shipped, and someone took their work seriously. Templates, labels, and bots all exist to make the second thing happen faster and more reliably.

8. Pre-launch checklist

Go through this list item by item before publishing the template set. First, the template chooser offers three kinds: a bug report (a YAML form requiring reproduction steps, version, and expected vs. actual results, auto-labelling bug and needs-triage), a feature request (problem first, proposal second, alternatives last), and a question (background, what was tried, where it got stuck, with a link to Discussions); blank issues stay on for two weeks of observation before deciding whether to close them. Second, the PR template lives at .github/pull_request_template.md with six fixed sections — what changed, why it changed, how it was tested, screenshots or recordings, the linked issue, and a checklist; a small PR should change no more than 300 lines; open a draft PR first when the direction is uncertain. Third, CONTRIBUTING.md has eight paragraphs — quick start, workflow, branch naming, commit messages, testing requirements, code style, code of conduct (referencing the Contributor Covenant), and release notes — and is linked prominently from the README. Fourth, the minimal label set has 8 labels with meanings written into CONTRIBUTING; bug and feature-request forms label automatically; the good first issue list is reviewed weekly, and anything unclaimed for over two weeks is rewritten or de-labelled. Fifth, bots do only three small jobs: automatic labelling, the automatic first reply (promising a human reply within 3 working days), and stale reminders (stale after 30 days, closed after another 14, with an explanatory comment before closing); stale never touches good first issue, help wanted, or bugs with reproduction steps. Sixth, the review checklist has five fixed items, reviews leave written traces, merges use squash, and after merging the contributor is thanked in the release and notified.

Six pitfalls, once more for emphasis. First, do not turn templates into a wall that keeps contributions out: every extra field loses a batch of contributors; only ask what a review must know. Second, do not pretend a Markdown template is a form: a Markdown template can be deleted at will, while required fields need a YAML form. Third, do not mix questions with bugs: usage questions go to Discussions, and the issue list keeps only work that genuinely needs fixing or building. Fourth, do not let a bot deliver the second reply for you: the promise in the automatic reply is one the maintainer must keep. Fifth, never close an issue silently: leave a comment explaining it, because contributors have a right to know where their work went. Sixth, do not wait until "someone files something" to add templates: the templates should already be in the repository before the first issue arrives — they are not prepared for people who have already contributed, but for the next person who wants to help and is hesitating over a blank text box.

Contribution funnel (fictional sample): 100 open the template picker, 70 submit, 45 are complete enough to review, 20 enter review, 12 get merged

Back to the maintainer at the start of this guide, stuck on a blank issue and a 2,000-line PR. With this template set installed, the same week looks like this: someone wants to report a bug, opens the chooser, and the form walks them through "what happened, how to reproduce it, which version", applying labels automatically on submit; someone wants a feature, and writes the problem first and the proposal second; someone wants a PR, and the template reminds them to split it smaller and discuss the direction in a draft first. Every morning you open the issue list and see not blank bodies and guessing games, but things you can review and act on directly. The narrow end of the open-source contribution funnel was never "nobody wants to help" — it was "people who want to help don't know where to start". Fix the entrance, and the helpers will walk in by themselves.

Views 4Comments 0

Comments (0)

ME
0/1000
Loading comments...
Browse projectsPublish your project

Related articles

Real photo: a woman in an office sticking colorful sticky notes in rows on a white wall, holding a pink note in her hand
Guide
Stop shimming with margins: Flexbox one-dimensional layout, explained plainly

Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.

Developer WorkflowFrontend EngineeringAI Coding
Real photo: top-down view of hands sorting handwritten index cards on a dark desk, with clipboards holding tables beside them
Guide
Put the data in a labeled box first: objects and JSON, explained plainly

One order is one object: table, dishes, total, paid — all filed by label. This guide follows MDN's Working with objects, JSON, and Object references: object literals, dot vs bracket notation, adding and deleting properties, for...in with hasOwn, methods and this, getters and setters, references vs copies, Object.assign and friends, null-prototype objects, JSON's strict rules, and stringify and parse with their number-precision trap.

Developer WorkflowFrontend EngineeringAI Coding
A developer with glasses types on a laptop at a wooden desk, an external monitor to the left showing C code on a dark background, a small plant on the desk
News
Microsoft's Coding Model Stops Playing Second Fiddle: MAI Code 2 Scores 96% of Opus 5.5 for 5% of the Cost — Read the Three Caveats First

On 17 November 2026, Microsoft launched MAI Code 2 and Code 2 Flash: the larger model has 77 billion active parameters and a one-million-token context, averaging 63.2% across four benchmarks — close to GPT-6.1 Sol and Claude Opus 5.5 — at $0.309 per task. Read the three caveats first: promotional pricing, the lowest score of the three, and no long-horizon work.

Developer WorkflowProduct LaunchModel Updates