Download ZIP

archive-warnings.md · 4.5 KiB · Markdown Raw

# 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

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:

<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:

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:

check https://fanfiction.lol/works/new and confirm the warning checkboxes reflect your changes
check https://fanfiction.lol/help/tags_warnings and confirm the warning descriptions are correct
checkhttps://fanfiction.lol/tos_faq and confirm the warning list is updated
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