# Archive Warnings Update Guide

This guide goes over all files that need to be updated when modifying archive warnings, and how to deploy those changes to production.

(Line numbers are specific to fflol)

## Files to Update

When adding, removing, or modifying archive warnings, you must update the following files:

### 1. Configuration File
**File:** `config/config.yml` (lines 257-272)

This file defines the canonical tag names for all archive warnings. Each warning has a `WARNING_*_TAG_NAME` constant.

Current warnings:
- `WARNING_DEFAULT_TAG_NAME`: "Choose Not To Use Archive Warnings"
- `WARNING_NONE_TAG_NAME`: "No Archive Warnings Apply"
- `WARNING_VIOLENCE_TAG_NAME`: "Graphic Depictions Of Violence"
- `WARNING_DEATH_TAG_NAME`: "Major Character Death"
- `WARNING_NONCON_TAG_NAME`: "Rape/Non-Con"
- `WARNING_ABLEISM_TAG_NAME`: "Ableism"
- `WARNING_COLONIALISM_TAG_NAME`: "Colonialism"
- `WARNING_HOMOPHOBIA_TRANSPHOBIA_TAG_NAME`: "Queerphobia"
- `WARNING_MISOGYNY_TAG_NAME`: "Misogyny"
- `WARNING_RACISM_TAG_NAME`: "Racism"
- `WARNING_SYSTEMIC_OPPRESSION_TAG_NAME`: "Systemic Oppression"
- `WARNING_FANTASY_OPPRESSION_TAG_NAME`: "Fantasy Oppression / Bigotry"
- `WARNING_RPF_TAG_NAME`: "Real Person Fiction (RPF)"
- `WARNING_INCEST_TAG_NAME`: "Incest"

When adding a new warning: Add a new `WARNING_*_TAG_NAME` constant with the canonical tag name.

When removing a warning: Remove the corresponding constant and update all references below.

### 2. Locale File (User-Facing Text)

File: `config/locales/views/en.yml` (lines 1641-1685)

This file contains the user-facing descriptions and headers for each warning under the `tags_warnings` section.

Each warning has:
- `header`: The display name shown to users
- `description`: The detailed explanation of what the warning means

When adding a new warning, add a new entry with the warning's key (snake_case version of the tag name), header, and description.

### 3. Help Page Template
File: `app/views/help/tags_warnings.html.erb`

This template displays the warning help page at `/help/tags_warnings`. 

When adding a new warning, add a new `<dt>` and `<dd>` pair:
```erb
<dt><strong><%= t(".your_new_warning.header") %></strong></dt>
<dd><%= t(".your_new_warning.description") %></dd>
```


### 4. FAQ Page
File: `app/views/home/tos_faq.html.erb` (line 26)

The FAQ contains a hardcoded list of required archive warnings.

When adding a new warning, add the warning name to the list on line 26.

### 5. Tag Creation Script

File: `script/ensure_required_tags.rb` (lines 11-35)

This script creates the canonical warning tags in the database. It's run during deployment.

When adding a new warning, add a new line:

```ruby
ArchiveWarning.create_canonical(ArchiveConfig.WARNING_YOUR_NEW_TAG_NAME)
puts "Created your new warning"
```

### 6. Model File

File: `app/models/archive_warning.rb` (lines 11-19)

The `warning_tags` method defines which tags are considered warnings. This is used for validation and filtering.

When adding a new warning, add the new tag name to the Set in the `warning_tags` method if it should be treated as a "warning" for filtering purposes (as opposed to "no warnings apply").

## Deployment Process

Please note I have a custom deployment script at `/home/brennan/cafe/fanfiction-lol/scripts/deploy-on-cafe.sh`

This script restores the database, restores Elasticsearch, builds and starts services, restarts Caddy and Cloudflare tunnel, reindex Elasticsearchs (important for search/filtering), and runs `script/ensure_required_tags.rb` to create/update warning tags in the database.

## Verification

After deployment, verify the changes are live:

1. check `https://fanfiction.lol/works/new` and confirm the warning checkboxes reflect your changes
2. check `https://fanfiction.lol/help/tags_warnings` and confirm the warning descriptions are correct
3. check`https://fanfiction.lol/tos_faq` and confirm the warning list is updated
4. finally, try filtering works by the new/modified warning to ensure Elasticsearch reindexing worked correctly

## Important Notes

- Tag names in config.yml must match exactly with the canonical tag names in the database
- The ensure_required_tags.rb script is idempotent, so it can be run multiple times without issues
- Elasticsearch reindexing is required for warning filtering to work correctly with new/modified warnings
- Always update all files, as missing one will cause inconsistencies between the UI, database, and help documentation
- The works form automatically pulls warnings from `ArchiveWarning.canonical.by_name`, so as long as the tags exist in the database, they will appear on the form