Release Notes: January 2026 Update

This document covers the new features deployed in the January 2026 release. If you're a first-time user or returning after the update, this guide will help you understand and use the new capabilities.

Table of Contents

1. Overview
2. New Features
3. Arrival Waves
4. Food Reserves
5. Visual Timeline
6. Sub-criteria Breakdown
7. Evaluator Attribution
8. Property → Food Plan Navigation
9. For Administrators: Migration Instructions
10. User Experience Guide
11. Troubleshooting

Overview

This release adds several key features for food production planning and property evaluation:

New Features

Arrival Waves

What it does: Instead of assuming everyone arrives at once, you can now model people arriving in waves over months or years.

Example scenario: - Wave 1 (Month 0): 5 core team members - Wave 2 (Month 6): 10 additional team members - Wave 3 (Month 18): 15 family members/dependents

How to use:

1. Go to Admin → Scenarios → Arrival Waves
2. Click "Add Arrival Wave"
3. Select the scenario or food plan this wave belongs to
4. Set:
5. Month: When this wave arrives (0 = start of plan)
6. People Count: How many people in this wave
7. Wave Name: Optional label (e.g., "Core Team", "Phase 2")
8. Wave Type:
   • Scheduled: Planned arrival
   • Contingent: Only if a trigger event occurs

Wave Types: - Scheduled: These arrivals will happen as planned - Contingent: These arrivals depend on a specific event (e.g., "If Taiwan crisis, 20 additional refugees")

Food Reserves

What it does: Track non-grown food sources to get a complete picture of food security.

Reserve Types:

How to use:

1. Go to Admin → Food → Food Reserves
2. Click "Add Food Reserve"
3. Select the food production plan
4. Set:
5. Reserve Type: Choose from the 5 types above
6. Total Calories: For finite reserves (stockpiles)
7. Monthly Calories: For ongoing purchases
8. Start/End Month: When this reserve is available
9. Cost: Optional cost tracking

Tips: - For stockpiles, set total_calories and leave monthly_calories blank - For ongoing purchases, set monthly_calories and leave end_month blank - Emergency reserves should have a long duration but be marked as last-resort

Visual Timeline

What it does: Shows an interactive chart on the Food Plan detail page with: - Stacked bar chart of food sources (grown, stored, purchased, emergency) - Line showing calories needed based on population - Stepped chart showing population over time - Gantt-style crop production schedule

How to use:

1. Navigate to any Food Production Plan
2. Scroll down to the "Food Production Timeline" card
3. Use the Months/Years toggle to change time scale
4. Hover over bars/lines for detailed values

Reading the chart: - Green bars: Calories from grown crops - Blue bars: Calories from stored food - Orange bars: Calories from purchases - Purple bars: Emergency reserves - Red line: Calories needed (based on population × daily target)

Key insight: If the stacked bars are below the red line, you have a food deficit for that period.

Sub-criteria Breakdown

What it does: Each of the 5 property evaluation dimensions (Location, Self-Sustainability, Cost/Value/Opportunity, Robustness, Glamor) can now be expanded to show the weighted sub-elements that evaluators consider.

How to use:

1. Go to any Property Detail page
2. Find the "Evaluation Scores" card
3. Click on any dimension name (e.g., "Location")
4. The panel expands to show 5 sub-criteria with:
5. Name and description
6. Relative weight (as percentage)

Example - Location sub-criteria: - Distance to Major Centers (28%) - Road Access Quality (21%) - Regional Services (14%) - Internet/Communications (21%) - Community Integration (14%)

For administrators: Sub-criteria can be customized in Admin → Properties → Dimension Sub-Criteria.

Evaluator Attribution

What it does: The property list now shows who has evaluated each property.

Where to see it: - Property List page now has an "Evaluators" column - Shows count badge and names of evaluators - Filter by evaluator using the sidebar dropdown

Why it matters: - Know which properties need more evaluations - Understand whose perspective the scores represent - Enable accountability in the evaluation process

Scoring Profiles

What it does: Create and apply different weighting configurations to see how property rankings change based on priorities.

Pre-built Profiles:

How to use:

1. Go to Properties → Weights (button on property list page)
2. Select a profile from the dropdown
3. See the dimension weights visualized as progress bars
4. Review how properties are ranked using those weights
5. Filter by evaluator to see single-evaluator rankings

Understanding the scores: - Each property dimension is scored 1-10 by evaluators - Dimension weights determine how much each contributes to the total - Site weight vs Region weight balances property-specific vs location factors - Combined percentage shows overall fit based on the profile's priorities

Creating custom profiles: Administrators can create new profiles in Admin → Properties → Scoring Profiles.

Evaluator Comparison

What it does: Shows how different evaluators' scores would rank properties differently.

How to use:

1. Go to Properties → Evaluator Comparison (from Weights page)
2. Select a scoring profile to use for calculations
3. View the comparison table showing:
4. Aggregate rank (average of all evaluators)
5. Each evaluator's rank for that property
6. Arrows indicating if a property ranks higher/lower for each evaluator

Reading the table: - Green up arrow: Property ranks higher for this evaluator - Red down arrow: Property ranks lower for this evaluator - No arrow: Same rank as aggregate

Why it matters: - Identifies properties where evaluators disagree - Helps understand different perspectives on property value - Enables informed discussion about evaluation criteria

Crop Auto-suggest

What it does: Automatically suggests an optimal crop mix for a food production plan based on target population, land size, and preferred optimization strategy.

Suggestion Modes:

How to use:

1. Navigate to any Food Production Plan detail page
2. Click "Auto-suggest" button in the Planned Crops section
3. Select a suggestion mode from the dropdown
4. Optionally adjust:
5. Max crops to suggest (1-20)
6. Planting year for the crops
7. Which categories to include (Trees, Annuals, Perennials, Livestock)
8. Click "Generate Suggestions"
9. Review the suggested crops with their:
10. Suggested hectares and quantity
11. Annual calorie contribution
12. Rationale (why this crop was chosen)
13. Select/deselect individual suggestions as needed
14. Click "Accept Selected" to add crops to your plan

Understanding the results: - Total Calories: Annual calorie production from all suggested crops - Surplus/Deficit: Percentage above/below your calorie target (green = surplus, red = deficit) - Land Used: Hectares allocated vs available - Production Timeline: When crops will reach full production

Tips: - Use "Quick Start" mode if you need food production within 1-2 years - Use "Low Maintenance" mode if labor will be limited - Check the "Replace existing planned crops" option to start fresh - Re-run with different modes to compare options

Property → Food Plan Navigation

What it does: Properties now show linked food production plans directly on their detail page.

How to use:

1. Go to any Property Detail page
2. Find the "Food Production Plans" card
3. See all plans linked to this property with:
4. Plan name and status
5. Target population
6. Planning horizon
7. Self-sufficiency percentage
8. Click to navigate directly to the plan
9. Use "Create Food Plan" to start a new plan pre-linked to this property

For Administrators: Migration Instructions

First-Time Migration

If this is a fresh deployment or first migration after the January 2026 update:

# SSH into your server
ssh user@your-server

# Navigate to the project
cd /path/to/CVTas

# Activate virtual environment
source venv/bin/activate

# Run all migrations
python manage.py migrate

# Verify migrations applied
python manage.py showmigrations scenarios food properties

Specific Migrations in This Release

Step-by-Step Migration

# 1. Backup database first (IMPORTANT)
pg_dump -h localhost -U cvtas_user cvtas_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Pull latest code
git pull origin master

# 3. Install any new dependencies
pip install -r requirements.txt

# 4. Run migrations in order
python manage.py migrate scenarios 0004_arrival_wave
python manage.py migrate food 0007_food_reserve
python manage.py migrate properties 0007_dimension_subcriteria
python manage.py migrate properties 0008_populate_default_subcriteria
python manage.py migrate properties 0009_scoring_profile
python manage.py migrate properties 0010_populate_default_profiles

# 5. Collect static files (if needed)
python manage.py collectstatic --noinput

# 6. Restart the application
sudo systemctl restart gunicorn
# or
sudo supervisorctl restart cvtas

Rollback Instructions

If something goes wrong:

# Restore database from backup
psql -h localhost -U cvtas_user cvtas_db < backup_YYYYMMDD_HHMMSS.sql

# Or rollback specific migrations
python manage.py migrate properties 0006_add_source_tracking_fields
python manage.py migrate food 0006_add_activity_level
python manage.py migrate scenarios 0003_populate_default_events

Verifying Success

After migration, verify with:

# Check migration status
python manage.py showmigrations

# Test the API endpoints
curl -u admin:password https://your-site.com/api/properties/dimension-subcriteria/breakdown/
curl -u admin:password https://your-site.com/api/food/plans/1/timeline_data/

# Check admin interface
# Navigate to /admin/ and verify new models appear:
# - Scenarios → Arrival Waves
# - Food → Food Reserves
# - Properties → Dimension Sub-Criteria

User Experience Guide

Typical Workflow

1. Evaluate a Property
2. Go to Properties → Select property
3. Review scores (click dimensions to see sub-criteria)

4. Check linked food plans or create new one

5. Plan Food Production

6. Create food plan linked to property
7. Add crops with planting years
8. Add food reserves (stockpiles, purchases)

9. Set up arrival waves for realistic population growth

10. Review Timeline

11. Go to Food Plan detail page
12. Review visual timeline chart
13. Check for deficit periods (red line above bars)

14. Adjust reserves or crop mix to close gaps

15. Compare Scenarios

16. Create multiple food plans with different assumptions
17. Use the timeline to compare when self-sufficiency is achieved

Quick Reference

Troubleshooting

Timeline shows "Unable to load timeline data"

Cause: API endpoint not responding or migrations not applied.

Fix: 1. Check migrations are applied: python manage.py showmigrations food 2. Check server logs: sudo journalctl -u gunicorn -f 3. Verify API endpoint: curl localhost:8000/api/food/plans/1/timeline_data/

Sub-criteria panel shows "Sub-criteria not available"

Cause: Data migration for sub-criteria didn't run.

Fix:

python manage.py migrate properties 0008_populate_default_subcriteria

Arrival waves not showing in timeline

Cause: Waves may be linked to scenario instead of food plan.

Fix: Ensure arrival waves have either scenario or food_plan set, and that the food plan is linked to the same scenario.

Food reserves show 0 calories

Cause: Either total_calories or monthly_calories must be set.

Fix: Edit the reserve in Admin and set the appropriate calorie field.

Related Documentation

• Food Planning Guide - Complete food production planning
• Scenario Planner - Multi-event scenario modeling
• Property System Guide - Property evaluation details
• Admin Guide - Administration tasks

Last updated: January 2026 Questions? Contact the CVTas team.