Developer Documentation

Getting Started

1. Make sure you have Python 3 installed by running python --version or python3 --version. If not, download it here. This project is known to work with Python 3.12 and 3.13, but other versions should work too.
2. Clone the repository to your local machine with git clone https://github.com/423S25/repo1.git.
3. Navigate to the directory where the repository was cloned. Run pip install -r requirements.txt or pip3 install -r requirements.txt to make sure you have all of the needed dependencies installed.
4. Create a file named .env in the root directory of the project with the following fields. Note that each field in your file should follow a format similar to this: NAME="value"
   • ADMIN_PASSWORD
   • STAFF_PASSWORD
   • VOLUNTEER_PASSWORD
   • SENDGRID_KEY- this is used for email notifications. Reach out to a developer if you need this and they can get you the correct key. We can't store this on github because SendGrid won't allow it to be stored on a public repository.
   • APP_SECRET_KEY- flask uses this for session management. You can view this for information on how to generate a key.
5. Run python app.py in the root project directory to start the site.
6. Go to http://127.0.0.1:5000 to view the current site.

Contributing

1. Make a branch on the GitHub repository.
2. Run git pull on the main branch.
3. Run git switch <branch-name>.
4. Do your work, add your feature, and save your changes to your branch.
5. Push your changes. Make sure you are on your branch, not main!
6. On GitHub, make a pull request to merge your changes into the main branch and resolve any merge conflicts.
7. Tag someone for a review.
8. Once two other contributors approve, merge your pull request.

Bug Tracking

To view a list of current and resolved bugs, go to the GitHub issues here.

Access Control

The three availabe users are:

• Administrator: has access to everything
• Staff: can update inventory, but cannot add or delete items
• Volunteer: currently the same as Staff

On local deployments, the passwords are pulled from your .env file (see the "Getting Started" section). If you are developing and sick of re-signing in after every server restart, consider temporarily changing app.config['SECRET_KEY'] to a constant value.

Project Structure

The current stucture is as follows:

• app.py: the main web server
• /templates: the HTML pages to be rendered
• /src/model: the database code, containing the Product, InventorySnapshot and User classes.
• /src/common: the Flask forms
• /static: static resources like images, fonts, and JS scripts
• /docs: the documentation pages (like the one you are viewing now!)

Testing

Developers should be sure to test the core functionality of the application with every contribution. At least one approving reviewer should do a code review and test each contribution.

Automated Building and Testing

There is a github action that will run the app and then test it with selenium. Right now, since the UI is going through a lof of changes, the tests are:

• logging in
• logging out
• adding a product

There are also unit tests in the automated-testing/unit directory. Developers are responsible for fixing/updating these tests as they add features.

How to release a new version

To release a new version of this software, update the code and send the updated code to the server.

Additional considerations

The code for this project is stored here. Developers should provide meaningful comments when contributing source code.