Welcome to the Coffee Tasting Sessions repository! This project aims to collect and analyze data from our monthly coffee tasting events to personalize coffee recommendations for participants.

• Introduction
• How to Participate
  • Fork the Repository
  • Clone Your Fork
  • Add Your Data
  • Commit and Push Your Changes
  • Create a Pull Request
• Automated Workflows
  • Data Validation
  • Automatic Branch Creation
  • Report Generation
• Templates
  • Using Templates
• Scripts
  • Validation Script
  • Report Generation Script

Our coffee tasting sessions are collaborative events where participants bring their own coffee beans, brew filter coffee, and taste different varieties. We collect detailed ratings and rankings for each coffee to understand individual preferences and provide personalized recommendations.

This repository stores all the data collected during these sessions, along with scripts for validation and report generation.

Click the "Fork" button at the top right of this repository to create a copy under your GitHub account.

git clone https://github.com/<your-username>/coffee-tasting.git
cd coffee-tasting

If you're bringing a new coffee to the session:

1. Copy the templates/coffee_template.yaml file into data/coffees/.
2. Navigate to data/coffees/.
3. Rename the file to your unique coffee_id (e.g., coffee_ethiopia_yirgacheffe.yaml).
4. Fill in the template with your coffee bean information.

If you're a new participant:

1. Copy the templates/participant_template.yaml file into data/participants/.
2. Navigate to data/participants/.
3. Rename the file to your participant_id (e.g., participant_jane_smith.yaml).
4. Fill in your participant information.

1. Switch to your participant branch:

   git checkout <session_date>/<participant_id>

2. Fill in your ratings:

   • Navigate to data/sessions/<session_date>/ratings/.
   • Open your <participant_id>.yaml file.
   • Fill in your ratings for each coffee.

3. Fill in your rankings:

   • Navigate to data/sessions/<session_date>/rankings/.
   • Open your <participant_id>.yaml file.
   • Fill in your rankings.

git add .
git commit -m "Add ratings and rankings for <participant_id>"
git push origin <session_date>/<participant_id>

Go to your forked repository on GitHub. Click on "Compare & pull request". Provide a descriptive title and description. Submit the pull request.

Every pull request triggers an automated validation workflow using GitHub Actions. The validate_data.py script checks:

1. Required fields are present.
2. Data types are correct.
3. References (e.g., coffee_id, participant_id) are valid.
4. Data is consistent.

When a new session is added:

1. The auto_branch_creation.yml workflow runs on push to master.
2. It creates a new branch for each participant named <session_date>/<participant_id>.
3. Templates are copied and placeholders are replaced with known information.

Upon merging data into master, the generate_reports.yml workflow:

1. Runs the generate_reports.py script.
2. Generates an HTML report for each session in the reports/ directory.
3. Commits and pushes the reports back to the repository.

Templates are provided in the templates/ directory for easy reuse:

• coffee_template.yaml
• participant_template.yaml
• session_ratings_template.yaml
• session_rankings_template.yaml

1. Navigate to the templates/ directory.
2. Copy the required template to the appropriate directory.
3. Rename the file as per the naming conventions.
4. Replace placeholders (enclosed in < >) with your data.

Use the following command to install all required Python packages before running any script:

uv sync

• Location: validate_data.py
• Purpose: Validates all YAML data files against predefined schemas using Pydantic.
• Usage: uv run validate_data

• Location: generate_reports.py
• Purpose: Generates HTML reports summarizing each session.
• Usage: uv run generate_reports