CONTRIBUTING.md Generator

A contributing guide is a set of instructions written for a stranger who wants to help. It answers a few plain questions: how do I get this running, how do I check my change, what does the project expect from me, and where do I send the result. Most of those answers are commands. When a command in the guide does not exist, the stranger’s first hour ends in an error message, and many of them do not come back.

That is why the quality of a guide is not mostly about tone. Warm words help, but the commands carry the weight. A guide that says npm run lint:fix when the project has no such script is worse than a short guide that says nothing about linting at all. The short one is incomplete. The wrong one is a trap.

What a newcomer needs before anything else

The Open Source Guides list four documents every project should include: an open source licence, a README, contributing guidelines and a code of conduct. They describe the CONTRIBUTING file as the place that tells your audience how to take part, and they name the practical contents directly: how to file a bug report, how to suggest a feature, and how to set up the environment and run the tests. They also suggest linking the file from the README, so people actually see it.

The order matters. A newcomer reads the README, follows a link, and arrives with a clone of the repository and a terminal. The first thing they type is the install step. The second is usually the test command, because running the tests before changing anything tells them whether the project works on their machine at all.

Both of those commands live in files the project already has. In a JavaScript project the scripts object of package.json holds them, and the npm documentation says plainly that npm test runs whatever command sits under the test property of that object. In a Python project the [project] table of pyproject.toml, defined by PEP 621, holds the metadata, including requires-python and the optional dependency groups a developer installs. A Rust project declares itself in the [package] table of Cargo.toml, where rust-version states the minimal supported Rust version. A Go module names its minimum Go version in the go directive, and since Go 1.21 that line is a requirement rather than a hint.

So the facts a guide needs are not opinions. They are already written down, in machine-readable form, a few folders away from the guide itself.

Setup and test commands that really work

The trouble is that guides are written once and projects keep moving. Someone renames lint to check, a team switches package managers, a makefile gains a setup target and loses deps. The manifest changes in the same commit, because the code would break otherwise. The guide does not, because nothing breaks when prose goes stale.

A lockfile adds another quiet failure. A guide that tells people to run yarn install in a project whose lockfile is pnpm-lock.yaml will appear to work, then produce a different dependency tree from everyone else’s. The command exists; it is simply the wrong one for this repository.

Makefiles deserve their own care because their syntax is older and stranger than it looks. The GNU make manual defines a rule as targets, a colon, then prerequisites, with recipe lines that start with a tab. The default goal is the first target in the file that does not start with a period, which is why so many makefiles put all or help first. A target whose name starts with a hyphen, or contains an equals sign, cannot be named on the command line at all, because make reads it as an option or a variable.

A tool that lists targets honestly has to say what it does not do: it does not expand variables, follow include lines or evaluate conditionals, so a target built from $(OUT) is reported as skipped rather than guessed.

Configuration formats have rules of their own. TOML is designed to map unambiguously to a hash table, and defining the same key twice is invalid. A reader that skips those rules will sometimes accept a broken pyproject.toml and write a guide from a table that the real tools would refuse to load.

Here is a worked example you can repeat in the tool, using the sample project it loads first. Its package.json defines eight scripts, its makefile defines six targets the reader can list, and its lockfile is pnpm-lock.yaml. Its old CONTRIBUTING.md names five commands. Four of them fail a check: yarn install and yarn dev belong to the wrong package manager, npm run lint:fix names a script that does not exist, and make check names a target the makefile never defines. Only pnpm test survives. That is 4 of 5, and nothing in the old file looked wrong to a human reader.

Style rules and EditorConfig

Style rules are the second thing newcomers trip over, usually in their first review. Two spaces or four? Tabs in the makefile? A newline at the end of every file? EditorConfig exists to answer those questions once, in a file that editors read. Version 0.17.2 of the specification describes an INI-like format of sections and key-value pairs, where each section name is a glob such as *.py or docs/**.

The resolution rules are short and easy to get backwards. Editors look for files named .editorconfig in the folder of the file being edited and in every parent folder, and the search stops at a file whose preamble sets root = true. Within one file, the pairs in a later matching section take precedence over an earlier one. Across files, the closer file wins. A value of unset removes a setting that was made earlier. Since version 0.15.0 there are no inline comments, so a semicolon in the middle of a value is part of the value.

In the sample project the root file sets indent_size = 2 for every file, and a second .editorconfig in the docs folder sets four for Markdown. A Markdown file at the top of the project is indented by two; docs/usage.md is indented by four. A guide that copies only the top file tells writers of documentation the wrong number.

The specification takes its own correctness seriously: it says a conforming core must pass the tests in the editorconfig-core-test repository. Those cases are a good discipline for anyone who reads these files. A resolver that lets the first matching section win instead of the last one fails exactly the precedence cases, which is the kind of mistake that looks fine on a small file and goes wrong on a real one.

The pull request path, conduct and security

The pull request is how most contributions arrive. Wikipedia describes it as a request that the maintainer pull the contributor’s change, also called a merge request on some systems, and notes that the maintainer has to merge it for the change to become part of the code. A guide should name the branch to target. That branch is a fact only the maintainer knows for certain, so it is better typed than guessed.

Commit conventions belong here too. The Conventional Commits specification, version 1.0.0, ties fix to a patch release, feat to a minor one, and a BREAKING CHANGE footer or an exclamation mark after the type to a major one, while allowing other types for everyday work. Some projects also ask for a sign-off. The git documentation describes git commit -s as adding a Signed-off-by trailer whose meaning depends on the project, for example agreement to the Developer Certificate of Origin, which is published as version 1.1. Git will not turn the option on by default, so a guide has to say so if the project needs it.

A code of conduct is, in Wikipedia’s general definition, a set of rules outlining the norms and responsibilities of a group. The Open Source Guides suggest keeping CODE_OF_CONDUCT in the project’s root and linking it from the CONTRIBUTING or README file, and they add a sharp warning: a code of conduct that is not enforced is worse than none, because it tells people the values are not taken seriously.

Security reports need a different door from ordinary bugs. The guides point out that a fix offered in a public pull request reveals the weakness before it is merged, and recommend a security policy in a SECURITY.md file that explains how to report problems privately. The licence matters for a related reason: the Legal Side guide notes that without a licence or other agreement, contributions stay exclusively with their authors, so nobody, not even the maintainer, may use or change them.

That is why the report looks for 7 community files: a README, a licence, a contributing guide, a code of conduct, a security policy, issue templates and a pull request template. Each one answers a question a newcomer would otherwise have to ask in public.

Keeping the guide in step with the project

The durable fix is to treat the guide as derived data. If every command in it is traced to the file and key that define it, the guide can be checked the same way the code is checked. When the script moves, the trace breaks, and someone notices on the same day rather than months later.

This method has limits, and they are worth stating. Reading files is not running them: a script can exist and still fail on a fresh machine, and a makefile target can depend on tools the guide never mentions. Variables, includes and conditionals in makefiles are not evaluated. Lockfiles are recognised by name, not opened. Nothing here can tell whether the code of conduct is enforced or whether anyone reads the security inbox. What the trace can promise is narrower and still useful: every command a newcomer copies from the guide is one the project itself defines, today.