Managed Standard Files
Standard files copied into every repository carry a DO NOT EDIT header; they are changed at their source, never in the repository that received them.
- Kind
- Convention
- Domain
- Documentation & Metadata
- Applies at
./- Status
- Stable
- Source · managed
Makefile
01 Defines
The marker and handling rules for files that an external tool generates and keeps identical across repositories: a first-line DO NOT EDIT header, and the expectation that local edits will be overwritten on the next sync.
02 Applies when
- A file should be identical in every repository — the root
Makefile, the lifecycle runner, area READMEs, release and security guides. - A file is generated from the repository’s structure rather than written by hand, such as
CODEMAP.md. - Part of a file is shared and part is repository-owned, as in
.gitignore.
03 Boundaries
- Repository-specific detail does not go into a managed file; it goes into the file the managed one delegates to, such as
scripts/build/repository.mk. - A managed file states shared conventions; it is not the place to record a repository’s own exceptions.
Expected behaviour
- 01The header is the first line, or the first line after a shebang or XML declaration, written in the file’s own comment syntax.
- 02Changes to a managed file are made at its source and arrive in every repository on the next update.
- 03Managed files delegate repository-specific values to repository-owned files beside them.
- 04Externally generated files such as
CODEMAP.mdare listed in.prettierignore, so local formatting does not fight the generator. - 05Files that mix shared and local content fence the managed part between explicit markers.
Behaviour#
Some files express a convention that should read the same everywhere. Copying them by hand guarantees drift, so an external tool owns them: it writes them into each repository and overwrites them when the standard changes. The header tells a reader, before they start editing, that this is not the place to make the change.
- 01
Notice the header
DO NOT EDITon the first line marks the file as managed - 02 Find the source Change the standard file in the tool that manages it
- 03 Propagate The next update rewrites the file in every repository
- 04 Keep local values local Anything repository-specific goes in the file the standard delegates to
Forms of the header#
The marker adapts to each file’s comment syntax but always opens with the same words.
| File | Header form |
|---|---|
Makefile, .editorconfig, *.yml | # DO NOT EDIT: … shell-style comment |
.devcontainer/lifecycle/run-parts.sh | After the shebang, as a # comment |
Area README.md, docs/RELEASING.md | <!-- DO NOT EDIT: … --> HTML comment |
.assets/img/*.svg | After the XML declaration, as an XML comment |
CODEMAP.md | <!-- DO NOT EDIT: Generated from the repository structure … --> |
.gitignore | A fenced >>> managed:gitignore >>> block |
Delegation keeps them identical#
A managed file stays identical only if it never needs a repository-specific
value. The root Makefile shows how: it is the same everywhere, and it reads
the repository’s component lists from scripts/build/repository.mk. The
lifecycle runner is the same everywhere, and runs whatever scripts the
repository places in each <event>.d/ directory.
Examples#
# DO NOT EDIT: This file is programmatically generated and managed by an external tool.
# It is a standard file that is copied and maintained in every repository. Any changes will be overwritten.
#
# Repository command surface.
#
# Repositories keep this file identical and declare their concrete component
# lists in `scripts/build/repository.mk`.
Partly managed files mark exactly which lines the tool owns:
# >>> managed:gitignore >>>
# Generated automatically. Changes within this block may be overwritten.
...
# <<< managed:gitignore <<<
# User-managed ignores
# Entries below this line are maintained manually and are never overwritten.
# Externally generated / managed files.
CODEMAP.md
managed-*.yaml