Example README

This is an example of what we expect in a README.

What?

A summary of the purpose of this piece of software, for example: Delivery of Learnosity assessments to students and reporting student results to teachers.

Diagram

A diagram showing all of the following:

  • project inputs
  • projects end users
  • project outputs
  • project data stores

(see mermaid documentation on how to create these diagrams)

For example:

graph LR
    subgraph project_components[Hypothetical Service]

        project_api[Hypothetical Service API]
        project_frontend[Hypothetical Service Frontend]
        subgraph datastores[Data Stores]
        postgres[PostgreSQL]
            queue[SQS queue service]
        end
    end

    subgraph inputs[Inputs]
        event_platform_input[Event Platform]
            cloud_canvas[Cloud Canvas API]
            identity[Identity Server]
    end


    subgraph end_users[End Users]
        student[Student]
            administrator[Administrator]
    end

    subgraph outputs[Outputs]
        event_platform_out[Event Platform]
    end

    event_platform_input -->|Canvas Change Events| project_api
    cloud_canvas -->|Canvas User API get| project_api
    identity -->|Authentication of users| project_frontend

    project_frontend -->|Views a thing| student
    administrator -->|Creates things| project_frontend

    project_api -->|Sends create and view messages| event_platform_out

Where?

A list of links to deployed software For example:

CI/CD

A link to CI/CD for this repository For example:

Administration

A list of links to operational information, for example:

Local Install

A set of comprehensive instructions to install from scratch on a developer workstation. We suggest you test these with a member from another team. For example:

Mac

In this source directory:

  1. Install homebrew
  2. Install python 3.10 using homebrew brew install [email protected]
  3. Install virtualenv and virtualenvwrapper pip install virtualenv virtualenvwrapper
  4. Create virtual environment for project mkvirtualenv project_name -p /opt/homebrew/opt/[email protected]/bin/python3
  5. Install project requirements pip install -r requirements.txt

Known Issues and Fixes

If your system python does not include pip, you will need to make sure pip is installed :

python -m ensurepip # if your system python is at least 3.4

If your system python isn't at least 3.4, you will need to use your system package manager to install pip.

Windows

In this source directory:

  1. Install python
  2. Open project in pycharm
  3. Set interpreter installed python 3.10
  4. Open shell
  5. Install project requirements pip install -r requirements.txt

Run tests locally

A set of instructions to run tests locally, for example:

pytest

Run service locally

A set of instructions to run service locally, for example:

Mac (service)

python manage.py runserver

Windows (service)

py manage.py runserver

Code owners can be found in CODEOWNERS file