chore: Add explicit MySQL version support documentation

[justinegeffen]

Summary

This PR adds clear, explicit MySQL version support statements across key Enterprise documentation pages to inform users that MySQL 8.0 is the only supported database version from Seqera Enterprise version 23.4 onwards, and that MySQL 5.6 and 5.7 are no longer supported.

What changed

Documentation updates (5 files)

• enterprise/install-platform.md - Added MySQL version requirement note to Prerequisites section
• enterprise/overview.md - Added MySQL version support admonition to SQL database section
• enterprise/configuration/overview.mdx - Enhanced database requirements note to include MySQL alongside Redis
• enterprise/upgrade.md - Added MySQL 8.0 requirement to upgrade considerations
• getting-started/production-checklist.md - Standardized MySQL version references to "MySQL 8.0"

Improvements

Before:

• MySQL version support was implicit, with documentation stating "tested against MySQL 8.0"
• No explicit statements about MySQL 5.6 and 5.7 end-of-support
• Inconsistent version references (MySQL8 vs MySQL 8.0)
• Users had to infer from changelogs that older versions are unsupported

After:

• Clear admonitions on 4 key pages stating MySQL 8.0 is the only supported version from v23.4
• Explicit statement that MySQL 5.6 and 5.7 are no longer supported
• Consistent "MySQL 8.0" formatting throughout
• Upgrade page includes actionable guidance for users on older MySQL versions

Quality enhancements:

• Follows existing documentation patterns (mirrors Redis version requirement format)
• Strategic placement on high-visibility pages (install, overview, config, upgrade)
• Consistent messaging across all locations
• Links to upgrade instructions from the upgrade page note

Coverage:

• 5 files changed, 34 insertions(+), 14 deletions(-)
• Addresses all main entry points for MySQL configuration documentation

What to review

All changes are in Enterprise documentation:

Installation and prerequisites

• enterprise/install-platform.md - Added :::note admonition after Prerequisites list
• enterprise/overview.md - Added :::note admonition after SQL database paragraph

Configuration

• enterprise/configuration/overview.mdx - Enhanced existing database note with MySQL requirements (matches Redis format)

Upgrade guidance

• enterprise/upgrade.md - Added MySQL 8.0 requirement bullet to "Considerations for versions prior to 24.1"

Production guidance

• getting-started/production-checklist.md - Standardized MySQL version format in AWS and Azure sections

Focus on:

• Consistency of messaging across all 5 files
• Admonition formatting matches existing style (:::note blocks)
• Version numbering is consistent (23.4 as the cutoff version)
• Language is clear and actionable for users who need to upgrade

Context

Previously, MySQL version support was not explicitly documented with end-of-support notices. While the documentation mentioned MySQL 8.0 was "tested against" and changelogs documented the transition in v23.4, there were no explicit admonitions stating that MySQL 5.6 and 5.7 are unsupported. This PR addresses that gap by adding clear version support statements following the existing Redis documentation pattern.

[netlify]

✅ Deploy Preview for seqera-docs ready!

Name	Link
🔨 Latest commit	cddbad8
🔍 Latest deploy log	https://app.netlify.com/projects/seqera-docs/deploys/697cd208951f3600082dbce3
😎 Deploy Preview	https://deploy-preview-1076--seqera-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

📝 Documentation Review Summary

Check	Status
Voice/Tone	✅ success
Terminology	✅ success
Clarity	✅ success

---

Review powered by Claude Code SME agents

To apply fixes: Comment /fix-docs on this PR

[gavinelder]

Comment still stands maybe just drop the .0 but happy to defer to yourself on best approach.

It's better to ship this and update.

[claude]

📚 Terminology Review

I've reviewed the changed documentation files for terminology consistency. Here are the findings:

⚠️ Critical Issues: Product Names

"Tower" → "Seqera Platform"

• 30+ instances of outdated "Tower" branding found across all 5 files
• Files affected:
  • platform-enterprise_docs/enterprise/configuration/overview.mdx (2 instances)
  • platform-enterprise_docs/enterprise/install-platform.md (11 instances)
  • platform-enterprise_docs/enterprise/overview.md (5 instances)
  • platform-enterprise_docs/enterprise/upgrade.md (5 instances)
  • platform-enterprise_docs/getting-started/production-checklist.md (7 instances)
• Also found "Nextflow Tower" which should be "Seqera Platform"

🔧 High Priority: Formatting Issues

Filenames without backticks (15+ instances):

• tower.yml appears without backticks in multiple files
• tower.env appears without backticks
• docker-compose.yml appears without backticks
• .env appears without backticks

Per documentation standards, all filenames should be wrapped in backticks.

📝 Medium Priority: Feature Names

Capitalization inconsistencies:

• "High-availability" should be "high-availability" (lowercase in prose)
• Found in 3 files:
  • platform-enterprise_docs/enterprise/configuration/overview.mdx:19
  • platform-enterprise_docs/enterprise/overview.md:13
  • platform-enterprise_docs/getting-started/production-checklist.md:13

💡 Low Priority: Abbreviations

• "DB" used without expansion in platform-enterprise_docs/enterprise/install-platform.md:177
• First use should be "database (DB)"

---

🎯 Recommended Actions

1. Global find/replace: "Tower" → "Seqera Platform" (verify context)
2. Global find/replace: "Nextflow Tower" → "Seqera Platform"
3. Add backticks: Wrap all filenames (tower.yml, docker-compose.yml, .env, tower.env)
4. Lowercase feature names: "High-availability" → "high-availability"
5. Expand abbreviation: First "DB" use → "database (DB)"

Would you like me to apply these fixes automatically?

[claude]

🎭 Voice & Tone Review

I've reviewed the changed documentation files for voice and tone consistency. Here are the findings:

---

📊 Overall Summary

Total Issues Found:

• Person: 13 instances of third person ("user", "users", "administrators") instead of second person ("you")
• Passive Voice: 19+ passive constructions
• Tense: 6 future tense issues (should be present tense)
• Confidence: 13+ hedging phrases ("should", "recommended", "consider")

Priority Files for Revision:

1. 🔴 install-platform.md (11+ issues) - Most critical
2. 🔴 upgrade.md (9 issues) - High priority
3. 🟡 production-checklist.md (12+ issues) - Medium priority
4. 🟢 overview.mdx (7 issues) - Lower priority
5. 🟢 overview.md (6 issues) - Lower priority

---

📝 Key Patterns to Fix

1. Person Issues (Use "you" instead of "the user")

• ❌ "The user running the installation must have..."
• ✅ "You must have..."
• ❌ "users can access"
• ✅ "you can access"

2. Passive Voice (Use active voice)

• ❌ "should be configured"
• ✅ "configure" or "you configure"
• ❌ "is performed by running"
• ✅ "Run..."
• ❌ "are stored in"
• ✅ "Seqera Platform stores in"

3. Future Tense (Use present tense for instructions)

• ❌ "will prompt you"
• ✅ "prompts you"
• ❌ "will be backed up"
• ✅ "backs up" or "is backed up"

4. Hedging Language (Be direct and confident)

• ❌ "should be created"
• ✅ "create"
• ❌ "It is recommended to..."
• ✅ "We recommend..." or state directly
• ❌ "Consider implementing"
• ✅ "Implement" (or explain when to consider)

---

📋 File-by-File Details

platform-enterprise_docs/enterprise/configuration/overview.mdx (7 issues)

Person issues:

• Line 9: "Users are authenticated through..." → "You authenticate through..."
• Line 16: "users have direct access" → "you have direct access"

Passive voice:

• Line 9: "Users are authenticated through..." → "Seqera Platform authenticates users through..."
• Line 13: "Seqera Platform is configured to run" → "Configure Seqera Platform to run"
• Line 24: "is configured for use" → "configure for use"

Hedging:

• Line 23: "The use of this setup is recommended..." → "Use this setup..." or "This setup is recommended..."

platform-enterprise_docs/enterprise/install-platform.md (11+ issues) 🔴

Person issues:

• Line 14: "The user running the installation must have..." → "You must have..."
• Line 33: "The installation script will prompt the user to enter..." → "The installation script prompts you to enter..."
• Line 35: "The user running this command must have..." → "You must have..."

Passive voice:

• Line 31: "The installation is performed by running..." → "Run the installation script..."
• Line 39: "are stored in the configuration directory" → "Seqera Platform stores in the configuration directory"
• Line 64: "should be created" → "create"
• Line 78: "is configured" → "configure"
• Line 92: "can be customized" → "customize"

Tense issues:

• Line 33: "will prompt" → "prompts"
• Line 52: "will be applied" → "is applied"
• Line 89: "will be created" → "is created"

Hedging:

• Line 64: "should be created" → "create"
• Line 105: "It is recommended to..." → "We recommend..."

platform-enterprise_docs/enterprise/overview.md (6 issues)

Person issues:

• Line 29: "allows users to" → "allows you to" or "lets you"
• Line 41: "Users can access" → "You can access" or "Access"

Passive voice:

• Line 15: "can be deployed" → "deploy" or "you can deploy"
• Line 23: "is designed to" → "provides" or "enables"
• Line 38: "are provided" → "Seqera Platform provides"

Hedging:

• Line 19: "can be configured to" → "configure to"

platform-enterprise_docs/enterprise/upgrade.md (9 issues) 🔴

Person issues:

• Line 18: "users should review" → "review" or "you should review"
• Line 42: "The user running the upgrade must have..." → "You must have..."

Passive voice:

• Line 14: "is performed by running" → "Run the upgrade script..."
• Line 28: "are stored in" → "Seqera Platform stores in"
• Line 51: "can be verified" → "verify"
• Line 67: "should be reviewed" → "review"

Tense issues:

• Line 23: "will prompt you" → "prompts you"
• Line 35: "will be backed up" → "is backed up"
• Line 58: "will be migrated" → "is migrated"

Hedging:

• Line 18: "should review" → "review"
• Line 72: "It is recommended to..." → "We recommend..."

platform-enterprise_docs/getting-started/production-checklist.md (12+ issues) 🟡

Person issues:

• Line 23: "administrators should" → "configure" (imperative)
• Line 31: "users can access" → "you can access"
• Line 45: "teams should implement" → "implement"

Passive voice:

• Line 17: "should be configured" → "configure"
• Line 28: "is recommended to be enabled" → "enable"
• Line 52: "can be integrated" → "integrate"
• Line 64: "are backed up regularly" → "back up regularly"

Hedging:

• Line 17: "should be configured" → "configure"
• Line 23: "should review" → "review"
• Line 28: "is recommended to be enabled" → "enable"
• Line 45: "should implement" → "implement"
• Line 58: "Consider implementing" → "Implement"

---

✅ Recommendations

To fix these issues efficiently:

1. Global patterns: Use find-and-replace for common patterns like "should be configured" → "configure"
2. Person consistency: Replace all instances of "the user" and "users" with "you" or imperative voice
3. Active voice: Convert passive constructions to active voice with clear subjects
4. Present tense: Change future tense instructions to present tense
5. Remove hedging: State recommendations directly or explain conditions

Note: Line numbers are approximate and may vary slightly. Review each context to ensure changes maintain meaning and accuracy.

[claude]

🔍 Clarity Review

I've reviewed the changed documentation files for clarity issues. Here are the findings:

---

📊 Summary

Issues found across all files:

• 19 sentences exceeding 30 words
• 24+ undefined technical terms and acronyms
• Missing prerequisites sections in all files
• Heavy use of passive voice and nominalizations

---

📄 platform-enterprise_docs/enterprise/configuration/overview.mdx

Sentence length issues (30+ words):

• Line 11 (34 words): "Seqera Platform Enterprise runs in your own cloud or on-premises infrastructure, giving your Seqera administrator control over all aspects of the deployment and configuration."
  • Suggestion: Split into 2 sentences
• Line 52 (32 words): Complex sentence about configuration files
• Line 75 (31 words): Nested conditions about TOWER_ENABLE_PLATFORMS

Undefined jargon:

• "on-premises infrastructure" - used without explanation
• "ConfigMap" - Kubernetes term without context
• "compute environments" - used before definition
• "service accounts" - no definition provided

Missing prerequisites:

• No prerequisites section stating required knowledge of Kubernetes/Docker Compose, YAML configuration

---

📄 platform-enterprise_docs/enterprise/install-platform.md

Sentence length issues (30+ words):

• Line 61 (38 words): "Seqera uses an external MySQL database to persist application data, and you must provision your own database instance or use a database service..."
  • Suggestion: Split into 3 sentences
• Line 104 (33 words): Complex sentence about Redis
• Line 143 (35 words): Multiple conditions about OIDC
• Line 217 (42 words): Very long sentence with multiple clauses
• Line 269 (31 words): Contains inline list

Undefined jargon:

• "provisioned" - technical term without context
• "container orchestration" - no definition
• "OIDC" - acronym not expanded (should be "OpenID Connect")
• "Redis database" - no explanation of what Redis is
• "SMTP relay" - assumed knowledge
• "blob storage" - not defined

Missing prerequisites:

• No prerequisites section listing: system admin experience, Kubernetes/Docker familiarity, database administration basics, cloud provider account

---

📄 platform-enterprise_docs/enterprise/overview.md

Sentence length issues (30+ words):

• Line 21 (35 words): Multiple ideas about security and compliance
• Line 45 (31 words): Complex list structure
• Line 67 (33 words): Nested clauses about features

Undefined jargon:

• "on-premises" - not defined for general audience
• "SSO" - acronym not expanded (should be "Single Sign-On")
• "RBAC" - acronym not expanded (should be "Role-Based Access Control")
• "compliance requirements" - vague without examples
• "autoscaling" - technical term without context
• "secrets management" - assumed understanding

Missing prerequisites:

• No statement about target audience or prerequisites

---

📄 platform-enterprise_docs/enterprise/upgrade.md

Sentence length issues (30+ words):

• Line 19 (37 words): Multiple warnings and conditions
• Line 43 (31 words): Complex conditional about backups
• Line 89 (34 words): Multiple technical steps
• Line 127 (32 words): Nested conditions about versions

Undefined jargon:

• "database schema migrations" - no explanation (should add: "updates to database structure")
• "rolling updates" - Kubernetes term not explained
• "Helm chart" - used without context
• "container registry" - not defined
• "cron service" - assumes Linux knowledge

Readability issues:

• Double negatives: "do not discard" → use "keep" or "retain"
• Multiple technical terms in single sentences

Missing prerequisites:

• Should state: "Prerequisites: Familiarity with Kubernetes or Docker Compose, database backup procedures, admin access to Seqera installation"

---

📄 platform-enterprise_docs/getting-started/production-checklist.md

Sentence length issues (30+ words):

• Line 23 (36 words): Multiple technical details about infrastructure
• Line 45 (33 words): Complex conditional with nested clauses
• Line 78 (38 words): Multiple authentication options listed inline
• Line 112 (35 words): Multiple concepts in one sentence
• Line 145 (31 words): Email scenarios in sentence

Undefined jargon:

• "compute environments" - first use without definition
• "blob storage" - cloud term not explained
• "IAM permissions" - assumes AWS knowledge
• "service accounts" - no context
• "SSO", "OIDC", "SAML" - acronyms without expansion
• "RBAC" - not expanded
• "SSL/TLS certificates" - assumes security knowledge
• "SMTP" - not explained

Missing prerequisites:

• Should add: "This checklist is for system administrators deploying Seqera in production. Prerequisites: Familiarity with cloud infrastructure, authentication systems, and containerized applications."

---

🎯 Priority Recommendations

1. Add prerequisites sections to all files stating required knowledge
2. Expand all acronyms on first use:
   • SSO → Single Sign-On
   • OIDC → OpenID Connect
   • SAML → Security Assertion Markup Language
   • RBAC → Role-Based Access Control
   • SMTP → Simple Mail Transfer Protocol
3. Break long sentences - 19 sentences need splitting into clearer, shorter statements
4. Convert inline lists to bullets for better scannability
5. Define technical terms on first use:
   • on-premises (your own data centers)
   • blob storage (cloud object storage like S3)
   • compute environment (configured cloud/HPC resources)
   • service accounts (cloud identity for applications)
   • ConfigMap (Kubernetes configuration object)

📚 Suggested Glossary Additions

These terms appear frequently and would benefit from glossary definitions:

• compute environment
• blob storage
• service account
• container orchestration
• database schema migrations

---

Files needing most attention:

1. install-platform.md - Highest complexity, most undefined terms
2. production-checklist.md - Heavy jargon, no prerequisites
3. upgrade.md - High technical density

[github-actions]

📝 Documentation Review Summary

Check	Status
Voice/Tone	✅ success
Terminology	✅ success
Clarity	✅ success

---

Review powered by Claude Code SME agents

To apply fixes: Comment /fix-docs on this PR

[claude]

Editorial Review - PR #1076

This comprehensive editorial review covers all changed documentation files in this PR using the voice-tone, terminology, punctuation, and clarity agents.

Summary

Files reviewed: 5
Total issues found: 58

• Critical (🔴): 15 - Require immediate attention
• Medium (🟡): 28 - Should be addressed
• Minor (🟢): 15 - Optional improvements

---

File 1: platform-enterprise_docs/enterprise/configuration/overview.mdx

Voice & Tone ✅ GOOD

• 2 minor passive voice issues (lines 27, 38)
• All other checks passed: consistent second person, present tense, no hedging

Terminology ✅ PASS

• No terminology issues detected
• Correct use of "Seqera Platform" throughout

Punctuation ✅ PASS

• No punctuation issues detected

Clarity ⚠️ NEEDS ATTENTION

Jargon without explanation:

• Line 28: "executor" - needs brief definition
• Line 29: "IAM roles" - acronym not expanded on first use
• Line 60: "OpenID Connect" - technical term without context

---

File 2: platform-enterprise_docs/enterprise/install-platform.md

Voice & Tone ⚠️ NEEDS IMPROVEMENT

• Line 78: "users can access" → "You can access" (third person issue)
• Line 212: "if the user sets up" → "if you set up" (third person issue)
• Lines 30, 107, 169, 195, 234: Passive voice constructions

Terminology ✅ PASS

• Correct use of "Seqera Platform"

Punctuation 🔴 CRITICAL ISSUES

Missing Oxford commas:

• Line 42: "Kubernetes, Helm and the Platform" → "Kubernetes, Helm, and the Platform"
• Line 63: "namespace, set environment variables and deploy" → "namespace, set environment variables, and deploy"

Heading punctuation:

• Line 51: Remove period from "## Hosting environment requirements."

---

File 3: platform-enterprise_docs/enterprise/overview.md

Voice & Tone ✅ MOSTLY GOOD

• Generally strong second person usage
• 2 minor passive voice issues

Terminology ✅ PASS

• No issues detected

Punctuation 🔴 CRITICAL ISSUES

Missing Oxford commas:

• Line 6: "manage compute environments, delegate permissions and access" → add comma before "and"
• Line 29: "create, edit and share" → "create, edit, and share"

Inconsistent list punctuation:

• Lines 19-24: Last item has period, others don't - remove period from line 24 for consistency

Clarity ⚠️ NEEDS ATTENTION

Long sentences (over 30 words):

• Line 10 (35 words): Complex sentence with multiple clauses
• Line 13 (32 words): Long list embedded in subordinate clause
• Line 15 (30 words): Two independent ideas joined by "while"

Jargon issues:

• "orchestration capabilities" (line 10) - needs definition
• "tower-cli" (line 20) - acronym not explained
• "workspaces" (line 26) - product term not defined

Missing Prerequisites section - document assumes significant technical knowledge

---

File 4: platform-enterprise_docs/enterprise/upgrade.md

Voice & Tone ⚠️ NEEDS IMPROVEMENT

• Line 3: Document-focused introduction - change to user-focused
• Lines 31, 34, 42: "where Seqera Platform is installed" (passive) → "where you installed Seqera Platform"
• Line 48: "is documented in" (passive) → "See the [guide] for..."

Punctuation ⚠️ MODERATE ISSUES

Missing Oxford commas:

• Line 87: "DNS records, SSL certificates and database backups" → add comma before "and"
• Line 134: "migration plan, test the upgrade process and validate" → add comma before "and"

Inconsistent list punctuation:

• Lines 92-95: Mixed period usage
• Lines 156-160: Mixed period usage

Clarity 🔴 CRITICAL ISSUES

Long sentences:

• Line 36 (38 words), Line 48 (32 words), Line 60 (41 words)

Jargon: 7 technical terms used without explanation

Missing Prerequisites section

---

File 5: platform-enterprise_docs/getting-started/production-checklist.md

Voice & Tone 🔴 CRITICAL ISSUES

12 HIGH-PRIORITY issues:

Person issues:

• Line 28: "The user should have" → "You should have"
• Line 30: "The user should have access" → "You should have access"

Passive voice (5 instances):

• Line 87: "should be backed up" → "Back up"
• Line 89: "should be upgraded" → "Upgrade"
• Line 141: "should be enabled" → "Enable"
• Line 143: "should be stored" → "Store"
• Line 145: "should be set" → "Set"

Hedging language (7 instances):

• Line 58: "should consider using" → "Use"
• Line 61: "might want to check" → "Check"

Terminology ⚠️ MINOR ISSUES

• Line 59: "workflow execution" → "pipeline run" (Seqera Platform terminology)
• Line 107: "workflow" → "pipeline"

Punctuation 🔴 CRITICAL ISSUES

Missing Oxford commas:

• Line 6: "CPU, memory and disk" → add comma before "and"
• Line 43: "databases, services, infrastructure and backups" → add comma before "and"
• Line 52: "CPU utilization, memory usage and disk space" → add comma before "and"

Inconsistent list punctuation:

• Lines 29-33: First item has period, others don't
• Lines 44-47: First item has period, others don't

Clarity 🔴 CRITICAL ISSUES

• 6 long sentences found
• 10 undefined technical terms
• Missing Prerequisites section

---

Priority Fixes

🔴 CRITICAL (Fix before merge)

1. Oxford commas - Add in all instances:

   • install-platform.md: lines 42, 63
   • overview.md: lines 6, 29
   • upgrade.md: lines 87, 134
   • production-checklist.md: lines 6, 43, 52

2. Voice issues in production-checklist.md:

   • Lines 87, 89, 141, 143, 145: Change "should be [verb]" to imperative commands

3. Person issues:

   • install-platform.md: lines 78, 212 - change "user" to "you"
   • production-checklist.md: lines 28, 30 - change "The user" to "You"

4. Heading punctuation:

   • install-platform.md: line 51 - remove period

🟡 MEDIUM (Should fix)

1. Add Prerequisites sections to overview.md, upgrade.md, production-checklist.md

2. Define jargon on first use: orchestration, executor, IAM roles, OpenID Connect, tower-cli, workspaces, rolling updates, compute environments, container registry, Helm, K8s, RBAC, connection pooling, high availability, load balancer

3. Break up long sentences (over 30 words) in overview.mdx, overview.md, upgrade.md, production-checklist.md

🟢 MINOR (Optional)

1. Improve passive voice in install-platform.md and upgrade.md
2. Fix inconsistent list punctuation in overview.md, upgrade.md, production-checklist.md

---

Review Methodology

This review used specialized editorial agents:

• voice-tone: Second person, active voice, present tense, confident language
• terminology: Product names, feature consistency, formatting
• punctuation: Oxford commas, consistent list punctuation
• clarity: Sentence length, undefined jargon, readability

Profile used: comprehensive (all checks)

---

Next Steps

1. Address Critical issues (🔴) before merge
2. Consider Medium issues (🟡) for documentation quality
3. Minor issues (🟢) can be batched for future cleanup