# Config Deserves Better > A manifesto for configuration: 13 principles that make it designed, safe to change, accountable and open to every actor. The manifesto is a draft. It argues that configuration — the settings people use to control how a product behaves, through settings screens, APIs, configuration files or automation — deserves the same design, testing and tooling as the code it controls. Feedback is welcome as a pull request or issue at https://github.com/reverse-gitops/configdeservesbetter.dev. ## Pages - [Home](https://configdeservesbetter.dev/): The manifesto in full. - [Markdown](https://configdeservesbetter.dev/manifesto.md): The same manifesto as plain Markdown. ## Principles ### Promise 1: Designed - 1. Configuration deserves deliberate design: Name the concepts, define their behavior, decide the boundaries and plan how they evolve, with the same care as any other part of the domain model. - 2. Every setting has a cost: Every setting earns its place. Each one adds a concept to understand, combinations to test and a compatibility promise to keep. It has an owner and a carefully chosen name. When it is no longer needed, it is deprecated and migrated with care: removing it can break someone's workflow even when the code change is trivial. - 3. Configuration has a schema: Configuration is typed, and every change is validated before it can become active, not when the application trips over it. A schema checks structure; whether a valid value also behaves well is a matter for testing. - 4. Configuration evolves with the application: Schema changes are planned like API changes. The schema is versioned, existing configuration is migrated rather than abandoned, and an old version keeps working while its users move to the new one. Deprecation is visible wherever someone reads or writes the setting: in the UI, in API responses, in a pipeline's output and in an agent's context, with a replacement and a date. Removal is the last step, not the first. - 5. Configuration explains itself: Settings describe their meaning, defaults, valid values, dependencies and impact in a form both people and machines can read. A schema says what is valid; this says what a change will do. Neither a new colleague nor an agent should have to guess what a field does. ### Promise 2: Safe to change - 6. A change is a proposal before it's a fact: A change can be proposed, previewed and tested before it takes effect: a diff of what will change, a dry run, a test outside production, review where it matters. Tests cover what a schema can't: how a valid value behaves with real data and in combination with the settings around it. How much of this a change needs depends on the setting, the value and the context: a rate limit going from 100 to 110 is not the same as 100 to 100 million. Define that policy beforehand and assess every proposal against it. Safe doesn't mean slow: configuration goes live independently of application builds, with explicit rules for when a change takes effect. - 7. Previous configuration can be restored: Previous states are recorded, and restoring one is a normal operation, not an incident. Restoring configuration doesn't undo what already happened under it, so the consequences of a change are part of designing it. Nor does it bring back a revoked credential: secrets are rotated, not restored. ### Promise 3: Accountable - 8. Configuration follows least privilege: Access is granted per resource, or even per field: who may change what, not just who may get in. People, services and agents each have their own identity, and an agent acting on someone's behalf stays within the authority it was explicitly given. - 9. No anonymous changes, no unexplained changes: Every change records who, what, when and why. The why points to something people can follow: a ticket, a request, an incident, or the policy or automation that triggered it. When an agent or service acts on someone's behalf, both are recorded: who asked, and what made the change. - 10. Secrets stay secret: Secret values are exposed only to authorized consumers, for only as long as they need them. Access is auditable without recording the secret itself. ### Promise 4: Open to every actor - 11. The GUI is one client, not the only way in: Everything the UI can do, a documented API can do, because the UI uses that same API. Changes can be described declaratively and applied repeatedly with the same result, so teams can bring them into the tools they already use: GitOps, an OpenTofu provider, Kubernetes resources, an SDK. You don't have to build all of them; you have to make them possible, and ideally ship the one your users need most. - 12. Many writers, one set of rules: People, pipelines and agents all go through the same path: the same validation, permissions, review rules and audit trail, whichever interface they use. For every setting it is clear who is in charge. A setting managed from git shows up as such in the UI. Desired and applied state may differ for a while, during review or rollout, but drift is detected and shown to the people who can resolve it. - 13. Conflicts are detected, not silently overwritten: A concurrent change is detected and resolved explicitly: by a person, or by a strategy agreed on beforehand. That holds for a person and a pipeline just as much as for two people. ## Notes for crawlers and agents - Crawling, indexing, quoting, and training on this content are all permitted. See https://configdeservesbetter.dev/robots.txt for the Content Signals. - Machine-readable index of this site: https://configdeservesbetter.dev/sitemap.xml - There is no API on this domain; the site is documentation. Source: https://github.com/reverse-gitops/configdeservesbetter.dev - Related: https://reversegitops.dev/, a better write path for GitOps.