Example README

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

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

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

A list of links to deployed software For example:

• dev: dev.strongmind.com
• prod: strongmind.com

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

• https://github.com/StrongMind/culture/actions

A list of links to operational information, for example:

• Logs
• Exception Tracking
• Monitoring & Metrics Dashboard

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:

In this source directory:

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

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.

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

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

pytest

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

python manage.py runserver

py manage.py runserver

Code owners can be found in CODEOWNERS file