# CalOohPay v2.0.0 Release Documentation

## 📦 Release Information

- **Version**: 2.0.0
- **Release Date**: October 25, 2025
- **Type**: Major Release (Breaking Changes)
- **Compatibility**: Multi-timezone distributed teams
- **Test Coverage**: 27 tests (7 new timezone-specific tests)

## 🎯 Overview

Version 2.0.0 is a major release introducing comprehensive timezone support for distributed teams. This release includes breaking changes but provides significantly better accuracy for teams working across multiple timezones.

## 🚨 Breaking Changes

### 1. Timezone Handling Changed

**Before (v1.0.0):**
```bash
# Always used local system timezone
caloohpay -r "SCHEDULE_ID" -t "Europe/London"  # -t defaulted to local timezone
```

**After (v2.0.0):**
```bash
# Uses schedule timezone from PagerDuty API
caloohpay -r "SCHEDULE_ID"  # Automatically detects schedule timezone

# -t now overrides schedule timezone
caloohpay -r "SCHEDULE_ID" -t "America/New_York"  # Override for testing
```

### 2. API Changes

- `OnCallPeriod` constructor now requires `timezone` parameter
- `CommandLineOptions.timeZoneId` is now optional (`timeZoneId?: string`)
- All date calculations use Luxon DateTime instead of native Date

### 3. Default behaviour

- **Old**: Used local system timezone
- **New**: Uses schedule timezone from PagerDuty API
- **Override**: Use `--timeZoneId` to specify a different timezone

## ✨ New Features

### 1. Automatic Timezone Detection

The tool now automatically retrieves and uses each schedule's timezone from the PagerDuty API:

```bash
caloohpay -r "SCHEDULE_ID"
```

**Output shows timezone:**
```
Schedule name: Engineering Team Alpha
Schedule URL: https://company.pagerduty.com/schedules/PQRSTUV
Using timezone: America/New_York
```

### 2. Timezone Override

Override schedule timezone for testing or special cases:

```bash
# Override to New York timezone
caloohpay -r "SCHEDULE_ID" -t "America/New_York"

# Override to Tokyo timezone
caloohpay -r "SCHEDULE_ID" -t "Asia/Tokyo"

# Use UTC for calculations
caloohpay -r "SCHEDULE_ID" -t "UTC"
```

### 3. Multi-Timezone Support

Perfect for distributed teams:

```bash
# Each schedule uses its own timezone from PagerDuty
caloohpay -r "SCHEDULE_LONDON,SCHEDULE_NEWYORK,SCHEDULE_TOKYO"
```

### 4. Timezone Warning

Get notified when CLI timezone overrides schedule timezone:

```
Using timezone: America/New_York
Note: CLI timezone (America/New_York) overrides schedule timezone (Europe/London)
```

### 5. Daylight Saving Time Handling

Automatically handles DST transitions using Luxon.

## 📋 Prerequisites

- **Node.js**: v14 or higher
- **npm**: v6 or higher
- **PagerDuty API Token**: User token with schedule read permissions
- **Luxon**: v3.5.0 (installed automatically)

## 🚀 Installation

### Step 1: Clone and Checkout

```bash
git clone https://github.com/lonelydev/caloohpay.git
cd caloohpay
git checkout v2.0.0
```

### Step 2: Install Dependencies

```bash
npm install
```

### Step 3: Build

```bash
npm run build
```

### Step 4: Configure Environment

Create a `.env` file in the project root:

```env
API_TOKEN=your_pagerduty_api_token_here
```

### Step 5: Link Globally (Optional)

```bash
npm link
```

## 🔄 Migration from v1.0.0

### Step 1: Assess Impact

**Low Impact** if:
- You never specified `--timeZoneId`
- Your schedules in PagerDuty have correct timezone settings
- You want more accurate calculations

**Medium Impact** if:
- You always specified `--timeZoneId`
- You want to maintain exact v1.0.0 behaviour
- You need to test with different timezones

### Step 2: Update Commands

#### Scenario A: No Timezone Specified (Most Users)

**v1.0.0:**
```bash
caloohpay -r "SCHEDULE_ID"  # Used local timezone
```

**v2.0.0 (no change needed):**
```bash
caloohpay -r "SCHEDULE_ID"  # Now uses schedule timezone from PagerDuty
```

**Result**: More accurate! Calculations now match schedule's actual timezone.

#### Scenario B: Timezone Always Specified

**v1.0.0:**
```bash
caloohpay -r "SCHEDULE_ID" -t "Europe/London"  # Forced timezone
```

**v2.0.0 (same command works):**
```bash
caloohpay -r "SCHEDULE_ID" -t "Europe/London"  # Still works, overrides schedule timezone
```

**Result**: Same behaviour, but you'll see a warning if schedule timezone differs.

### Step 3: Verify Output

Run a test calculation and verify:

1. **Timezone is correct**: Check "Using timezone:" line in output
2. **Day counts match**: Compare weekday/weekend counts
3. **Total compensation**: Should be more accurate in v2.0.0

### Step 4: Update Scripts/Automation

If you have automated scripts:

```bash
# Old script (v1.0.0)
#!/bin/bash
caloohpay -r "SCHEDULE1,SCHEDULE2" -t "Europe/London"

# New script (v2.0.0) - Option 1: Use schedule timezones
#!/bin/bash
caloohpay -r "SCHEDULE1,SCHEDULE2"

# New script (v2.0.0) - Option 2: Keep explicit timezone
#!/bin/bash
caloohpay -r "SCHEDULE1,SCHEDULE2" -t "Europe/London"
```

## 📖 Usage Examples

### Example 1: Automatic Timezone (Recommended)

Let CalOohPay use the schedule's timezone from PagerDuty:

```bash
caloohpay -r "SCHEDULE_ID"
```

**Output:**
```
┌─────────────────┬─────────────────────────────────────┐
│ rotaIds         │ 'SCHEDULE_ID'                       │
│ timeZoneId      │ undefined                           │
│ since           │ '2024-09-01T00:00:00.000+01:00'    │
│ until           │ '2024-10-01T10:00:00.000+01:00'    │
└─────────────────┴─────────────────────────────────────┘
────────────────────────────────────────
Schedule name: Engineering Team Alpha
Schedule URL: https://company.pagerduty.com/schedules/SCHEDULE_ID
Using timezone: America/New_York
User, TotalComp, Mon-Thu, Fri-Sun
John Smith, 275, 3, 2
```

### Example 2: Distributed Teams

Different schedules with different timezones:

```bash
caloohpay -r "SCHEDULE_LONDON,SCHEDULE_NYC,SCHEDULE_TOKYO"
```

Each schedule will use its own timezone from PagerDuty for accurate OOH calculations.

### Example 3: Testing with Override

Test calculations in a different timezone:

```bash
# Test how it would look in UTC
caloohpay -r "SCHEDULE_ID" -t "UTC"

# Test with team's actual timezone
caloohpay -r "SCHEDULE_ID" -t "America/Los_Angeles"
```

### Example 4: Daylight Saving Time

Calculations automatically handle DST transitions:

```bash
# Period spanning DST change (October 2024)
caloohpay -r "SCHEDULE_ID" -s "2024-10-20" -u "2024-11-05"
```

## 🌍 Supported Timezones

All IANA timezone identifiers are supported:

### Common Timezones

#### Americas
- `America/New_York` (Eastern Time)
- `America/Chicago` (Central Time)
- `America/Denver` (Mountain Time)
- `America/Los_Angeles` (Pacific Time)
- `America/Toronto`
- `America/Sao_Paulo`

#### Europe
- `Europe/London` (UK)
- `Europe/Paris` (CET)
- `Europe/Berlin` (CET)
- `Europe/Amsterdam`
- `Europe/Dublin`
- `Europe/Madrid`

#### Asia/Pacific
- `Asia/Tokyo`
- `Asia/Singapore`
- `Asia/Hong_Kong`
- `Asia/Dubai`
- `Asia/Kolkata`
- `Australia/Sydney`
- `Pacific/Auckland`

#### Special
- `UTC` (Coordinated Universal Time)

**Full list**: See [PagerDuty Timezone Documentation](https://developer.pagerduty.com/docs/1afe25e9c94cb-types#time-zone)

## 🧪 Testing

### Run All Tests

```bash
npm test
```

**Expected output:**
```
Test Suites: 5 passed, 5 total
Tests:       27 passed, 27 total
```

### New Timezone Tests

v2.0.0 includes 7 new timezone-specific tests:

1. Europe/London timezone calculations
2. America/New_York timezone calculations
3. Asia/Tokyo timezone calculations
4. UTC timezone handling
5. Daylight saving time transitions
6. Cross-timezone comparisons
7. Default UTC behaviour

## 📊 Understanding Timezone Impact

### Example: New York Team

**Schedule timezone in PagerDuty**: `America/New_York`

**Shift**: Monday 10:00 AM to Tuesday 10:00 AM

| Timezone Used | Weekdays | Weekends | Total |
|---------------|----------|----------|-------|
| UTC (wrong) | 2 | 0 | £100 |
| America/New_York (correct) | 1 | 0 | £50 |

**Result**: v2.0.0 gives accurate calculations based on actual timezone.

### Example: Distributed Team

**Team A** (London): `Europe/London`  
**Team B** (New York): `America/New_York`  
**Team C** (Tokyo): `Asia/Tokyo`

```bash
caloohpay -r "TEAM_A,TEAM_B,TEAM_C"
```

Each team's OOH calculation uses their correct timezone automatically!

## 🔧 Troubleshooting

### Issue: "Using timezone: UTC" but expected different timezone

**Cause**: Schedule in PagerDuty doesn't have timezone set, or API doesn't return it.

**Solution**:
```bash
# Explicitly set timezone
caloohpay -r "SCHEDULE_ID" -t "Europe/London"
```

### Issue: Different results than v1.0.0

**Cause**: v2.0.0 uses schedule timezone, v1.0.0 used local timezone.

**Solution**: This is expected! v2.0.0 is more accurate. To match v1.0.0:
```bash
caloohpay -r "SCHEDULE_ID" -t "Your/Local/Timezone"
```

### Issue: Warning about timezone override

**Message**: `Note: CLI timezone (UTC) overrides schedule timezone (Europe/London)`

**Cause**: You specified `--timeZoneId` that differs from schedule's timezone.

**Solution**: This is informational. Either:
- Remove `-t` to use schedule timezone
- Keep `-t` if override is intentional

## 🎯 Best Practices

### 1. Let PagerDuty Provide Timezone

**Recommended:**
```bash
caloohpay -r "SCHEDULE_ID"
```

**Why**: Most accurate, uses schedule's actual timezone.

### 2. Only Override When Needed

Use `-t` only for:
- Testing different timezone scenarios
- Schedules without timezone in PagerDuty
- Special reporting requirements

### 3. Verify Schedule Timezones in PagerDuty

Ensure your schedules have correct timezone settings:
1. Go to PagerDuty → Schedules
2. Click on schedule
3. Check timezone setting
4. Update if incorrect

### 4. Document Timezone Choices

If you override timezone, document why:
```bash
# Using UTC for global reporting consistency
caloohpay -r "ALL_SCHEDULES" -t "UTC"
```

## 📈 Performance

- **Same performance as v1.0.0** for single schedules
- **Slightly slower** for multiple schedules (fetches timezone per schedule)
- **Test suite**: ~0.8s (vs ~0.6s in v1.0.0)

## 🐛 Reporting Issues

Found a bug in v2.0.0?

1. Check it's not expected behaviour change
2. Review migration guide above
3. Create issue with:
   - Version: v2.0.0
   - Schedule timezone from PagerDuty
   - CLI command used
   - Expected vs actual timezone used
   - Expected vs actual day counts

## 📄 Additional Resources

- [Full Changelog](../CHANGELOG.md)
- [v1.0.0 Documentation](v1.0.0-RELEASE.md)
- [Main README](../README.md)
- [PagerDuty Timezone Docs](https://developer.pagerduty.com/docs/1afe25e9c94cb-types#time-zone)
- [Luxon Documentation](https://moment.github.io/luxon/)

## 🎉 What's Next?

See the [Development Roadmap](../README.md#-development-roadmap) for upcoming features:
- CSV output
- Configurable rates
- Enhanced output formatting
- NPM package distribution

---

**Version**: v2.0.0  
**Last Updated**: October 25, 2025  
**Maintained**: Yes (active development)  
**Recommended**: Yes for all new deployments