Revision of archive-warnings.md

brennan revised this gist 1 month ago. Go to revision

1 file changed, 1 insertion, 1 deletion

archive-warnings.md

			@@ -22,7 +22,7 @@ Current warnings:
22	22		- `WARNING_ABLEISM_TAG_NAME`: "Ableism"
23	23		- `WARNING_COLONIALISM_TAG_NAME`: "Colonialism"
24	24		- `WARNING_HOMOPHOBIA_TRANSPHOBIA_TAG_NAME`: "Queerphobia"
25		-	- `WARNING_MISOGYNY_TAG_NAME`: "Misogyny" (Note: defined in config but not currently used)
	25	+	- `WARNING_MISOGYNY_TAG_NAME`: "Misogyny"
26	26		- `WARNING_RACISM_TAG_NAME`: "Racism"
27	27		- `WARNING_SYSTEMIC_OPPRESSION_TAG_NAME`: "Systemic Oppression"
28	28		- `WARNING_FANTASY_OPPRESSION_TAG_NAME`: "Fantasy Oppression / Bigotry"

brennan revised this gist 1 month ago. Go to revision

1 file changed, 109 insertions

archive-warnings.md(file created)

		@@ -0,0 +1,109 @@
1	+	# Archive Warnings Update Guide
2	+
3	+	This guide goes over all files that need to be updated when modifying archive warnings, and how to deploy those changes to production.
4	+
5	+	(Line numbers are specific to fflol)
6	+
7	+	## Files to Update
8	+
9	+	When adding, removing, or modifying archive warnings, you must update the following files:
10	+
11	+	### 1. Configuration File
12	+	File: `config/config.yml` (lines 257-272)
13	+
14	+	This file defines the canonical tag names for all archive warnings. Each warning has a `WARNING_*_TAG_NAME` constant.
15	+
16	+	Current warnings:
17	+	- `WARNING_DEFAULT_TAG_NAME`: "Choose Not To Use Archive Warnings"
18	+	- `WARNING_NONE_TAG_NAME`: "No Archive Warnings Apply"
19	+	- `WARNING_VIOLENCE_TAG_NAME`: "Graphic Depictions Of Violence"
20	+	- `WARNING_DEATH_TAG_NAME`: "Major Character Death"
21	+	- `WARNING_NONCON_TAG_NAME`: "Rape/Non-Con"
22	+	- `WARNING_ABLEISM_TAG_NAME`: "Ableism"
23	+	- `WARNING_COLONIALISM_TAG_NAME`: "Colonialism"
24	+	- `WARNING_HOMOPHOBIA_TRANSPHOBIA_TAG_NAME`: "Queerphobia"
25	+	- `WARNING_MISOGYNY_TAG_NAME`: "Misogyny" (Note: defined in config but not currently used)
26	+	- `WARNING_RACISM_TAG_NAME`: "Racism"
27	+	- `WARNING_SYSTEMIC_OPPRESSION_TAG_NAME`: "Systemic Oppression"
28	+	- `WARNING_FANTASY_OPPRESSION_TAG_NAME`: "Fantasy Oppression / Bigotry"
29	+	- `WARNING_RPF_TAG_NAME`: "Real Person Fiction (RPF)"
30	+	- `WARNING_INCEST_TAG_NAME`: "Incest"
31	+
32	+	When adding a new warning: Add a new `WARNING_*_TAG_NAME` constant with the canonical tag name.
33	+
34	+	When removing a warning: Remove the corresponding constant and update all references below.
35	+
36	+	### 2. Locale File (User-Facing Text)
37	+
38	+	File: `config/locales/views/en.yml` (lines 1641-1685)
39	+
40	+	This file contains the user-facing descriptions and headers for each warning under the `tags_warnings` section.
41	+
42	+	Each warning has:
43	+	- `header`: The display name shown to users
44	+	- `description`: The detailed explanation of what the warning means
45	+
46	+	When adding a new warning, add a new entry with the warning's key (snake_case version of the tag name), header, and description.
47	+
48	+	### 3. Help Page Template
49	+	File: `app/views/help/tags_warnings.html.erb`
50	+
51	+	This template displays the warning help page at `/help/tags_warnings`.
52	+
53	+	When adding a new warning, add a new `<dt>` and `<dd>` pair:
54	+	```erb
55	+	<dt><strong><%= t(".your_new_warning.header") %></strong></dt>
56	+	<dd><%= t(".your_new_warning.description") %></dd>
57	+	```
58	+
59	+
60	+	### 4. FAQ Page
61	+	File: `app/views/home/tos_faq.html.erb` (line 26)
62	+
63	+	The FAQ contains a hardcoded list of required archive warnings.
64	+
65	+	When adding a new warning, add the warning name to the list on line 26.
66	+
67	+	### 5. Tag Creation Script
68	+
69	+	File: `script/ensure_required_tags.rb` (lines 11-35)
70	+
71	+	This script creates the canonical warning tags in the database. It's run during deployment.
72	+
73	+	When adding a new warning, add a new line:
74	+
75	+	```ruby
76	+	ArchiveWarning.create_canonical(ArchiveConfig.WARNING_YOUR_NEW_TAG_NAME)
77	+	puts "Created your new warning"
78	+	```
79	+
80	+	### 6. Model File
81	+
82	+	File: `app/models/archive_warning.rb` (lines 11-19)
83	+
84	+	The `warning_tags` method defines which tags are considered warnings. This is used for validation and filtering.
85	+
86	+	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").
87	+
88	+	## Deployment Process
89	+
90	+	Please note I have a custom deployment script at `/home/brennan/cafe/fanfiction-lol/scripts/deploy-on-cafe.sh`
91	+
92	+	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.
93	+
94	+	## Verification
95	+
96	+	After deployment, verify the changes are live:
97	+
98	+	1. check `https://fanfiction.lol/works/new` and confirm the warning checkboxes reflect your changes
99	+	2. check `https://fanfiction.lol/help/tags_warnings` and confirm the warning descriptions are correct
100	+	3. check`https://fanfiction.lol/tos_faq` and confirm the warning list is updated
101	+	4. finally, try filtering works by the new/modified warning to ensure Elasticsearch reindexing worked correctly
102	+
103	+	## Important Notes
104	+
105	+	- Tag names in config.yml must match exactly with the canonical tag names in the database
106	+	- The ensure_required_tags.rb script is idempotent, so it can be run multiple times without issues
107	+	- Elasticsearch reindexing is required for warning filtering to work correctly with new/modified warnings
108	+	- Always update all files, as missing one will cause inconsistencies between the UI, database, and help documentation
109	+	- 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

Newer Older