Repository File Templates

Every file the guide tells you to add to a repository, in the smallest version that works. Copy one, replace YOUR_ORG, YOUR_REPO, YOUR_DOCS_OWNER and the other placeholders, and cut what you won’t keep. Each template links to the chapter that explains why it says what it says.

The templates are released under CC0 1.0: paste them anywhere, with no attribution. The rest of the site stays under CC BY-NC-SA 4.0.

There is no code of conduct here: use the Contributor Covenant, version 3.0 as of October 2026, and put your contact line in it. It is CC BY 4.0, so it keeps its attribution.

Unzip it into a new folder and copy the files you need: each file sits at the path it goes to in the repository, and .github/ is a hidden folder on macOS and Linux. In a brand-new repository, you can unzip it at the root.

• README.md: What it does, how to install it, a first example, how to contribute. One screen.
• CONTRIBUTING.md: The reply you would otherwise retype: before you start, set up, pull requests, review.
• SECURITY.md: Supported versions, a private way to report, and a promise about timing.
• GOVERNANCE.md: Roles, how decisions are made, how to become a committer, how to step down.
• bug.yml: A bug report form that asks for the version, the expectation and the steps to reproduce.
• config.yml: Turns off blank issues and sends questions and vulnerabilities to the right place.
• pull_request_template.md: What changes, how to test it, a short checklist.
• CHANGELOG.md: A Keep a Changelog skeleton with an Unreleased section.
• CODEOWNERS: Default owners, plus one owner for the docs and one for CI.
• ARCHIVED.md: The notice to put above the README when the project is archived: status, alternative, migration.

# Project name

One sentence: what it does and for whom.

[![CI](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/YOUR_ORG/YOUR_REPO)](LICENSE)

![A screenshot or a short GIF of the project at work](docs/screenshot.png)

## Install

```sh
# the one command that installs it
```

## Usage

```sh
# the smallest example that does something useful
```

Expected output:

```text
what the reader should see
```

## Documentation

Link to the docs, or to `docs/` if they live in the repository.

## Contributing

Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## License

[MIT](LICENSE)

# Contributing

Thanks for taking the time. This page is the short version of how to send a change.

## Before you start

- For a bug, search the [open issues](../../issues) first. If it's new, open one with the steps to reproduce.
- For a feature or a larger change, open an issue and wait for a reply before writing code. It saves you a rejected pull request.
- Small fixes (a typo, a broken link) can go straight to a pull request.

## Set up

```sh
git clone https://github.com/YOUR_ORG/YOUR_REPO.git
cd YOUR_REPO
# install the dependencies
# run the tests
```

## Send a pull request

1. Fork the repository and create a branch from `main`.
2. Make the change. Add or update a test when behavior changes.
3. Run the tests and the linter locally.
4. Open the pull request and fill in the template.

We squash-merge, so the pull request title becomes the commit message. Write it like `fix(parser): handle empty input`.

## Review

A maintainer replies within a week. If nothing has happened after that, comment on the pull request once.

## Questions

Ask in [Discussions](../../discussions), not in issues.

## Code of conduct

Everyone taking part follows the [code of conduct](CODE_OF_CONDUCT.md).

# Security policy

## Supported versions

| Version | Supported                 |
| ------- | ------------------------- |
| 2.x     | Yes                       |
| 1.x     | Security fixes until DATE |
| < 1.0   | No                        |

## Report a vulnerability

Please don't open a public issue.

Use [private vulnerability reporting](https://github.com/YOUR_ORG/YOUR_REPO/security/advisories/new), or write to security@example.org.

Include the affected version, the steps to reproduce, and what an attacker gains.

## What to expect

- We acknowledge your report within 3 working days.
- We send a first assessment within 10 working days.
- We agree on a disclosure date with you. The default is 90 days after the report, sooner once a fix is released.
- We credit you in the advisory unless you ask us not to.

# Governance

## Roles

| Role        | Who                                        | Can                                         |
| ----------- | ------------------------------------------ | ------------------------------------------- |
| Contributor | Anyone                                     | Open issues and pull requests               |
| Committer   | Listed in [CODEOWNERS](.github/CODEOWNERS) | Review and merge pull requests              |
| Maintainer  | Listed in [MAINTAINERS.md](MAINTAINERS.md) | Release, change the roadmap, add committers |

## How decisions are made

- Most decisions happen in the pull request or the issue, by lazy consensus: if nobody objects within 5 working days, it goes ahead.
- A change to the public API, the license or this document needs an approval from a majority of the maintainers.
- If maintainers disagree, they vote. A tie is broken by the project lead.

## Becoming a committer or a maintainer

- A committer has had several pull requests merged over at least 3 months. A maintainer nominates them, and the maintainers approve.
- A maintainer is a committer who has reviewed other people's work for at least 6 months. Current maintainers vote.

## Stepping down

Maintainers who are inactive for 6 months are moved to emeritus. They can come back by asking.

## Changing this document

Open a pull request. It needs the approval described above for governance changes.

name: Bug report
description: Something doesn't work as documented.
labels: ['bug', 'needs triage']
body:
  - type: markdown
    attributes:
      value: |
        Thanks for the report. Search the [open issues](../issues) first: yours may already be there.
  - type: input
    id: version
    attributes:
      label: Version
      description: Output of `project --version`.
      placeholder: 2.4.1
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: What did you expect to happen?
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: What happened instead?
      description: Paste the error message or the output.
      render: shell
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to reproduce
      description: The smallest set of steps, or a link to a repository that reproduces it.
      placeholder: |
        1. Run `…`
        2. …
    validations:
      required: true
  - type: textarea
    id: environment
    attributes:
      label: Environment
      description: Operating system, runtime version, anything that might matter.

blank_issues_enabled: false
contact_links:
  - name: Question or idea
    url: https://github.com/YOUR_ORG/YOUR_REPO/discussions
    about: Ask questions and share ideas in Discussions, not in issues.
  - name: Security vulnerability
    url: https://github.com/YOUR_ORG/YOUR_REPO/security/advisories/new
    about: Report vulnerabilities privately. Don't open a public issue.

## What changes, and why

<!-- One or two sentences. Link the issue: Closes #123 -->

## How to test

<!-- Commands to run, pages to open, what to look at. -->

## Checklist

- [ ] I read [CONTRIBUTING.md](../CONTRIBUTING.md)
- [ ] Tests added or updated
- [ ] Docs updated
- [ ] Breaking change (describe the migration above)

# Changelog

All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and the project follows [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added

- A new thing.

## [1.0.0] - YYYY-MM-DD

### Added

- First public release.

[Unreleased]: https://github.com/YOUR_ORG/YOUR_REPO/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/YOUR_ORG/YOUR_REPO/releases/tag/v1.0.0

# The last matching pattern wins. Owners are asked to review pull requests that touch these paths.

# Default owners for everything
*             @YOUR_ORG/maintainers

# Documentation
/docs/        @YOUR_DOCS_OWNER

# CI and release automation
/.github/     @YOUR_ORG/maintainers

> [!WARNING]
> **This project is archived and no longer maintained.** The last release was VERSION on YYYY-MM-DD. It receives no bug fixes or security updates, and issues and pull requests are closed.
>
> - **Alternative:** [NAME](https://example.org), which covers the same ground and is maintained.
> - **Migration guide:** [docs/migrating.md](docs/migrating.md)
> - **Keep using it?** The license lets you fork it. If you do, open an issue and we'll link your fork here.