Add a Checkbox parameter (as well as a guide to contributing)

[atharvakale343]

Introduction

Before this PR, users of Flask-ML did not have any way to specify checkbox parameters as input. A checkbox parameter is one that has a label (i.e what the checkbox is for), and a boolean value.

This PR is part one of a two part PR series to add a checkbox to RescueBox-Desktop

Part 2 PR is here: UMass-Rescue/RescueBox-Desktop#338

This is a guide to how this PR was created:

If you want to follow along...

I recommend you follow through this guide. If you want to do so, checkout the commit hash before this PR:

git checkout 27b2ee0

1. Shell commands

# Clone the repo
git clone https://github.com/UMass-Rescue/Flask-ML.git

## Change Directory
cd Flask-ML

# Ensure you have a relatively new version of Python installed
python3 —-version

# Create a new python environment
python3 -m venv env

# Activate the environment (Windows is different)
source env/bin/activate

# Install this python package as a package into your environment
# -e stands for "editable"
# ".[dev]" means install the dev dependencies as specified in pyproject.toml 
pip install -e ".[dev]"

# Switch to a feature branch
# -c is used to "create" a new branch
git switch -c akale-add-checkbox

2. Open up the project in a text editor of your choice

Example: In VSCode, make sure you don't have any problems in the project by checking View -> Problems

3. Modifications to openapi.yaml

The file src/flask_ml/flask_ml_server/openapi.yaml contains all the definitions for what data looks like in this project. We want to add a Checkbox parameter.

See the changes to openapi.yaml in the files changed to see how this is achieved.

After making the above modifications, see step 4

4. Regenerate the pydantic models

Run the following bash command

make generate-models

If you are on Windows, then either get make, or copy the command from the Makefile and paste it in your shell.

Now, the file src/flask_ml/flask_ml_server/models.py will be automatically modified with the new schema.

See the changes to flask_ml_server/models.py in the files changed to see what this looks like.

5. Compiler assisted refactoring

After regenerating the models, you will see that the code breaks. If you are using VSCode (and have all the usual Python extensions installed), then View -> Problems will show you all the problems across the codebase. This is good because making any changes to our data model tells us exactly which parts of the codebase require changes. Let's fix them.

If you are following along, try fixing the code yourself. See the changes to the rest of the source files in the files changed section of this PR.

6. Writing tests

Let's run the tests and see what coverage we have:

make test

This generates a file htmlcov/index.html. Open up a web browser and open this file. You can also drag and drop it into a browser.

See the line coverage and make sure all the lines associated with your change are covered by tests.

Let's write tests. We can add an initialization of our new parameter in tests/constants.py. We can use this throughout our tests. Add tests as needed, and ensure cases are covered. See the modifications to tests/* in this PR for example. Re-open htmlcov/index.html to ensure coverage.

If you are working in a separate project that uses FlaskML, you can install the modified version to your project as follows:

pip3 install -e <full path to where you cloned this repo>

7. Modify the public facing website

Run the following shell commands:

cd website
npm install .
npx docusaurus start

This should show you a local build of the public website. We made the following changes:

8. Commit the changes

Commit the changes to Git. See the five commits below and which step it corresponds to above:

1. modify openapi.yaml -> Step 3
2. regenerate models -> Step 4
3. fix source code -> Step 5
4. add tests -> Step 6
5. add to website -> Step 7

That's it! We're done. You can release a new version to PyPI if you are happy with the changes.