README_template.md

Project name

(some badges for fun...)

A short desciption of the project.

Table of Contents [Optional]

A table of contents if useful for large/busy READMEs, look under the 'Miscellaneous -> Updating the table of contents' section for how to generate the table of contents. NB: Be sure to check the source of this template for the tags required to automatically generate the table of contents: toc and tocstop.

• Requirements for Development [Mandatory]
• Getting Started [Optional]
  • Configuring Environment [Optional]
  • Setup Steps [Optional]
• Running [Mandatory]
• Testing [Mandatory]
  • Testing Requirements [Optional]
  • Running Tests [Mandatory]
• Formatting and Linting etc. [Mandatory]
  • Formatting [Mandatory]
  • Linting [Mandatory]
  • Other Tooling (e.g. type checking)
• Deployment [Mandatory]
• Important Section [Optional]
• Miscellaneous [Mandatory]
  • Troubleshooting [Optional]
  • Updating the Table of Contents [Mandatory]
  • Less Important Section [Optional]

Requirements for Development [Mandatory]

Any application or service required to develop the application should be specified here in as much detail as is reasonable.

E.g. The following tools are required for development:

• ruby (version defined in the .ruby-version)
• python (use pyenv or something similar to install the python version specified in the Pipfile)

See the Troubleshooting section for any commonly encountered installation issues.

Getting Started [Optional]

Specify anything that is required before being able to run the application.

Configuring Environment [Optional]

Specify any required .env files or environmental variables that need to be set.

E.g. Create a .env file with the following values:

ENV_VAR_1 = var1
ENV_VAR_2 = var2

Setup Steps [Optional]

Specify if any steps are required to be run in a specific order for the application to be setup correctly.

E.g. Install the require dependencies:

pipenv install --dev
OR
bundle install
OR
yarn install

E.g. Create the database and seed the database with default data by running:

bundle exec rails db:setup

Running [Mandatory]

Specify how to run the application.

E.g. To run the application:

python runner.py
OR
flask run
OR
bundle exec rails

Testing [Mandatory]

Specify how to test the application.

Testing Requirements [Optional]

Specify if any dependencies (databases, brokers, etc.) need to be up and running before testing can commence.

Running Tests [Mandatory]

Specify how to run tests.

E.g. To run the test suite:

python -m pytest
OR
bundle exec rspec

Formatting and Linting etc. [Mandatory]

Describe how the project is formatted and linted and how to run these checks manually.

Formatting [Mandatory]

Specify how the project is formatted.

E.g. This project is formatted using black. To run formatting checks, run:

pipenv run black .

Linting [Mandatory]

Specify how the project is linted.

E.g. This project is linted using flake8. To lint the code, run:

pipenv run flake8

Other Tooling (e.g. type checking)

Specify any other tooling that verifies code quality etc.

E.g. This project uses static type checking using the mypy library, to run:

pipenv run mypy .

Deployment [Mandatory]

Specify how a deployment release should be created for this project, i.e. a release tag for an asset or to create a Docker image

E.g. This project uses a Docker image as the unit of deployment. To create a release for deployment, create a release in GitHub and wait for the GitHub action to create the Docker image.

The release version should align with the standards.

Important Section [Optional]

Use this level of section to specify anything else that is considered important for this application.

Miscellaneous [Mandatory]

This section allows for anything that does not clearly fit under the above sections.

Troubleshooting [Optional]

This section is especially helpful when requirements or dependecies are prone to be troublesome when installing or setting up.

E.g. If you are having trouble installing this, try this...

Updating the Table of Contents [Mandatory]

Always include this section so we can keep the table of contents up to date

To update the table of contents after adding things to this README you can use the markdown-toc node module. To run:

npx markdown-toc -i README.md

Less Important Section [Optional]

Use this level of section to specify anything that is considered less important for this application.