# Doorstop keeps requirements in the same repository as the code

> Doorstop stores each requirement as a YAML file in a directory, turns the directories into a tree of documents, and gives you a command line to link items across that tree, check its integrity and publish it as HTML.

**doorstop-dev/doorstop** — Requirements management using version control.

- Repository: https://github.com/doorstop-dev/doorstop
- Website: https://doorstop.readthedocs.io
- Stars: 687 · Forks: 171
- Language: Python
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/doorstop-dev-doorstop

## The data model is a directory of YAML files

Doorstop is a requirements management tool that facilitates the storage of textual requirements alongside source code in version control, and the model is described in three sentences. When a project uses the tool, each linkable item, a requirement or a test case for example, is stored as a YAML file in a designated directory. The items in each directory form a document. The relationship between documents forms a tree hierarchy. From that, the tool provides mechanisms for modifying the tree, validating item traceability and publishing documents in several formats. So the requirements are not rows in a database, they are files, and the document tree is a directory tree. The consequences follow from that choice. A requirement is reviewed in a pull request like any other change, it has a history and an author, and a merge conflict between two people editing the same requirement is a merge conflict between two files.

## Installing it and the Python version floor

The requirements are Python 3.10 or newer and a version control system for the requirements storage. Installation is with pip.

```sh
$ pip install doorstop
```

Or you can add it to a Poetry project.

```sh
$ poetry add doorstop
```

After installation the command is available on the command line.

```sh
$ doorstop --help
```

And the package can be imported under the same name.

```sh
$ python
>>> import doorstop
>>> doorstop.__version__
```

The package metadata is explicit about the supported range, with the Python constraint written as at least 3.10 and below 3.15, and the classifiers listing 3.10 through 3.14 individually. The project is licensed LGPLv3, the PyPI distribution is named Doorstop, the documentation is on readthedocs, and the development status classifier says Production/Stable. The last released version is 3.2 from 2026-07-10, following 3.1 in January and 3.0.2 in June 2025.

## Creating documents and adding items

You start in an existing version control working directory, or create one.

```sh
$ git init .
```

Then you create a parent requirements document, giving it a name and a path.

```sh
$ doorstop create SRD ./reqs/srd
```

Items are added to a document by name, and each call adds one.

```sh
$ doorstop add SRD
$ doorstop add SRD
$ doorstop add SRD
```

The naming in the example is worth noticing, because the document name is the prefix of the item identifiers, so the SRD document produces items called SRD001, SRD002 and SRD003. That is the mechanism behind the linking step later on, since a link names two items and each item identifier encodes its document. The naming convention is also what lets a requirement be referenced from a test case or from a design document without a separate identifier system, which is the point of the whole tool.

## Linking, checking and publishing

A child document is created with a parent, so the tree structure is explicit.

```sh
$ doorstop create HLTC ./tests/hl --parent SRD
$ doorstop add HLTC
```

Then items are linked across documents by identifier, and this is the traceability mechanism in its simplest form.

```sh
$ doorstop link HLTC001 SRD002
```

With that in place, running the tool with no arguments runs the integrity checks on the document tree.

```sh
$ doorstop
```

And publishing renders the documents as HTML into a directory.

```sh
$ doorstop publish all ./public
```

The three commands together are the whole loop of the tool. You write requirements and tests as files, you state which test covers which requirement, the tool checks that the links resolve and that the tree is consistent, and then you publish a report. The link direction in the example is the interesting detail, because it reads as the test linking to the requirement rather than the requirement listing its test, and the choice of which side holds the link is a decision each project makes for itself.

## The publishing side is richer than the readme shows

The package dependencies tell you what the publishing and validation layers can do. PyYAML and python-frontmatter handle the item files, the markdown package and python-markdown-math handle the prose, and plantuml-markdown pulls in diagram rendering. openpyxl is there for spreadsheet output, which is the format most compliance processes still ask for. Bottle is a small web framework, which is what powers the review and display interface, and requests is there for the integrations. The keyword list in the project metadata makes the intent clear, with requirements-management, version-control, traceability, documentation, certification, html and markdown. The certification keyword is the one that explains who uses it: this is a tool for projects that have to demonstrate to an auditor that every requirement has a test, which is a different job from planning the work.

## How the project is built and checked

The repository is a Poetry project with a Makefile that mirrors the continuous integration pipeline. The all target runs doctor, format, check, test, mkdocs and demo, and the comment calls it the set of tasks that determine CI status. The doctor target confirms the system dependencies are available using the verchew binary with an exit code flag. The bootstrap target installs the system dependencies through asdf, adding the Python and Poetry plugins before installing. The install target runs poetry install into a project-local virtual environment, and the lock file is regenerated only when it is not in continuous integration. The dev target runs sniffer continuously to re-run all the CI tasks when files change, and there is a demo target that runs a tutorial script inside the package so the tool can be exercised without any data of your own. The formatting is isort followed by black, and the static analysis covers mypy, pydocstyle and pylint, with the per-platform test workflows for Linux, macOS and Windows and a Codecov badge for coverage.

## Where this is the wrong choice

Three limits are worth naming. The first is that the tool is deliberately small, and there is no user interface for the review workflow, no assignment of requirements to people, no status tracking, no dashboards and no notification when a requirement changes. Those features exist in commercial requirements management systems, and Doorstop's answer is that the workflow lives in your version control and your issue tracker instead. If your organisation needs a requirement to have an owner and a status field visible to a manager, that is the gap. The second is that the items are YAML files with prose inside them, so a bulk edit, for example importing two hundred requirements from a spreadsheet, is a script you write rather than a feature you use, and the merge behaviour of concurrent edits to the same requirement is whatever Git does with text. The third is that the tool assumes the requirements belong in the repository, which is right for a team that already works that way and wrong for an organisation whose requirements live in a commercial tool under change control. What Doorstop gives in return is that a requirement is reviewed, versioned and traceable with the same machinery as the code it constrains, and that an auditor can be shown the git history.

## Conclusion

Doorstop suits a team that already keeps its source in Git and wants its requirements reviewed in the same pull requests, and it suits a regulated project that has to demonstrate traceability between requirements, tests and documents. It is the wrong tool if you need a heavyweight requirements management system with a user interface, scheduling, dashboards and workflow, because Doorstop deliberately has none of that and is a set of files plus a command line. It is also the wrong choice if your requirements live in a commercial tool and nobody wants them in Git. Before adopting it, decide where the item text lives, because each item is a YAML file with prose inside it, and read the validation and publishing steps, since running the tool with no arguments on the document tree is what performs the integrity checks. The last push was on 2026-10-17 and the current release is v3.2 from 2026-07-10.

## FAQ

### How do I install and start using Doorstop?

Install it with pip install doorstop or poetry add doorstop, then switch to a version control working directory, or create one with git init. Create a document with doorstop create SRD ./reqs/srd, add items with doorstop add SRD, link items across documents with doorstop link HLTC001 SRD002, run doorstop with no arguments to check the document tree, and publish with doorstop publish all ./public.

### How does Doorstop store requirements?

Each linkable item, a requirement or a test case for example, is stored as a YAML file in a designated directory, the items in each directory form a document, and the relationships between documents form a tree hierarchy. Because the items are files in version control, requirement changes are reviewed and merged like any other change.

### Which Python versions does Doorstop support?

Python 3.10 or newer, with the project constraint written as at least 3.10 and below 3.15 and classifiers for 3.10, 3.11, 3.12, 3.13 and 3.14. The project is licensed LGPLv3 and published to PyPI as Doorstop, with the current release being version 3.2.

## Sources

- [doorstop-dev/doorstop on GitHub](https://github.com/doorstop-dev/doorstop)
- [Issues](https://github.com/doorstop-dev/doorstop/issues)
- [Project website](https://doorstop.readthedocs.io)
- [README](https://github.com/doorstop-dev/doorstop/blob/develop/README.md)
- [Releases](https://github.com/doorstop-dev/doorstop/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/doorstop-dev-doorstop