Brief text description of the main purpose of the repo / application in the context of our platform.
Contents [if README is very large]
- Getting Started
- Making Changes
- General Operation
- To Do
Step by step guide for getting the application/project/tool set up for local development, including:
- Installation dependencies
- Any scripts or commands to run for local set up of the app
make(or similar) command for running tests
Making Changes (if applicable, i.e. if not fully obvious)
If noteworthy, please detail the general flow of making changes (a nice example is this workflow for making changes to a Chef Repo).
- Include your awesome diagrams here
- Consider including relevant context of the app/tool/project
- Operating considerations pertaining to how the app/project/tool runs in production
- Related applications / dependencies
One example is the General Operation section on the Solr indexers.
- Where is it deployed?
- Load balancer (internal or external)
- Cloud services
- How is it deployed?
- CI pipeline
- Specific deployment requirements
NB: If the repo isn't itself a deployable app (libaries, deploy tools like Edamame etc.), please still point out the CI pipeline used to run automated tests for the project.
- RUNBOOK.MD - some examples for inspiration:
- FAQ, for example: Q&A on Search API
- GOTCHAs and unresolved oddities
- WIP/info in case of newer repos or ongoing projects (i.e. cloud migrations)