Projects should include software version documentation and config
Introduction
To minimize the chance of incorrectly QA’d code getting into production, and ease debugging, it is important that development happens with tooling as close to production as can be achieved with the config options provided by your local development environment provider. Project READMEs should specify the tooling versions to be used in production for things like PHP, Database software, Caching layer, Search software, and Node. These versions should then be reflected in the configuration files for any local development and host configuration files committed to the repo for the project. Whenever these versions change, the README and configuration files should be updated to match. Local development environments should mirror the hosted website environment as closely as possible.
Decision
Initial project setup should involve updating README and matching local development configurations with the hosting environment, and any updates to the hosting environment should involve updating README and local development configuration as well.
Context
This is done for two main reasons:
- Prevent bugs caused by differences in the hosting environment and local setup.
- Ensure debugging is happening in an environment that matches production to avoid rework.
Consequences
- Project startup takes slightly longer.
- Documentation must be updated when the hosting environment changes.
- Architects must take responsibility for this.
Exceptions
- When client-dictated hosting configurations are not replicable with configuration options provided by default by your local development environment provider (ddev, lando, etc.)
- When setting up local environment is not possible / prohibited by the contract
Additional Resources
None