@keithba I have build a - private - GitHub action around https://github.com/sbdchd/squawk - for Postgres - that lints all our migrations files on each PR. The action extract raw SQL from the codebase and pass them into squawk.
It catches many exclusive locks migration or missing `index concurrently` that would otherwise have been release to production and causing downtime or degraded service. Maybe something you should start doing.
The code should be self-explanatory for a developer, if not add documentation inside the code.
I like to document anything the client will have at some point to touch.
Deployment and configuration must be documented.
There are two different things to consider:
- Your client beeing able to deploy or use what you give them.
- Your client beeing able to modify or add features to the existing code.
Always do the first one. I always discuss this kind of things before starting a project with the client. And everything discussed is mentioned inside the contract.