|
| 1 | +# Feature Specification: Migrate from Commento to Disqus Comments |
| 2 | + |
| 3 | +**Feature Branch**: `003-i-d-like` |
| 4 | +**Created**: 2025-11-27 |
| 5 | +**Status**: Draft |
| 6 | +**Input**: User description: "I'd like to disable commento and using Disqus instead for my comments, my id is @disqus_YWibv6kNhd" |
| 7 | + |
| 8 | +## User Scenarios & Testing *(mandatory)* |
| 9 | + |
| 10 | +### User Story 1 - Reader Uses Disqus Comments (Priority: P1) |
| 11 | + |
| 12 | +Blog readers can leave comments, reply to other comments, and engage in discussions using the Disqus commenting platform instead of Commento. |
| 13 | + |
| 14 | +**Why this priority**: This is the core migration requirement - switching the comment system from Commento to Disqus. Without this, existing comment functionality would be lost. |
| 15 | + |
| 16 | +**Independent Test**: Navigate to any published blog post on https://specoding.com/, scroll to the comments section, and verify the Disqus widget loads with the correct site identifier. |
| 17 | + |
| 18 | +**Acceptance Scenarios**: |
| 19 | + |
| 20 | +1. **Given** a reader views a blog post, **When** they scroll to the bottom, **Then** they see the Disqus comment widget (not Commento) |
| 21 | +2. **Given** Disqus is loaded, **When** a reader posts a comment, **Then** the comment appears in the Disqus thread |
| 22 | +3. **Given** existing functionality, **When** the migration is complete, **Then** all Disqus features work (replies, reactions, sorting) |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +### User Story 2 - Clean Removal of Commento (Priority: P2) |
| 27 | + |
| 28 | +The site no longer loads Commento JavaScript or CSS resources, reducing page weight and preventing conflicts between comment systems. |
| 29 | + |
| 30 | +**Why this priority**: Essential for clean migration - prevents confusion and resource waste from loading two comment systems simultaneously. |
| 31 | + |
| 32 | +**Independent Test**: View page source and network tab, verify no requests to cdn.commento.io or loading of commento-custom.css. |
| 33 | + |
| 34 | +**Acceptance Scenarios**: |
| 35 | + |
| 36 | +1. **Given** a blog post page loads, **When** inspecting network requests, **Then** no Commento CDN requests are made |
| 37 | +2. **Given** the page HTML, **When** searching for "commento", **Then** no Commento-related code appears |
| 38 | +3. **Given** the static files, **When** reviewing CSS files, **Then** commento-custom.css is removed |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +### Edge Cases |
| 43 | + |
| 44 | +- What happens if Disqus service is temporarily unavailable? |
| 45 | +- How does the page render if JavaScript is disabled? |
| 46 | +- Are there any existing Commento comments that need migration (likely not applicable for public CDN)? |
| 47 | +- Does dark mode work correctly with Disqus theme? |
| 48 | + |
| 49 | +## Requirements *(mandatory)* |
| 50 | + |
| 51 | +### Functional Requirements |
| 52 | + |
| 53 | +- **FR-001**: Blog posts MUST display Disqus comments at the end of post content |
| 54 | +- **FR-002**: Disqus MUST be configured with shortname `disqus_YWibv6kNhd` (extracted from provided ID) |
| 55 | +- **FR-003**: Commento configuration MUST be disabled in site parameters |
| 56 | +- **FR-004**: Commento partial template code MUST be removed or commented out |
| 57 | +- **FR-005**: Custom Commento CSS file MUST be removed from static assets |
| 58 | +- **FR-006**: Disqus widget MUST load asynchronously without blocking page render |
| 59 | +- **FR-007**: Comments MUST be associated with correct page URLs for thread identification |
| 60 | +- **FR-008**: Disqus MUST support threaded replies (default Disqus behavior) |
| 61 | +- **FR-009**: The comment section MUST remain visually consistent with blog design |
| 62 | +- **FR-010**: Site build process MUST complete without errors after migration |
| 63 | + |
| 64 | +### Assumptions |
| 65 | + |
| 66 | +- Hugo-clarity theme already includes Disqus support via `_internal/disqus.html` template |
| 67 | +- The Disqus shortname is `disqus_YWibv6kNhd` (format suggests this is the account identifier) |
| 68 | +- No comment data needs to be migrated (Commento was using public CDN, likely no persistent comments) |
| 69 | +- Disqus's default styling is acceptable or can be customized via Disqus admin panel |
| 70 | +- Site uses Hugo's standard Disqus integration pattern |
| 71 | +- Readers are familiar with Disqus (widely used commenting platform) |
| 72 | + |
| 73 | +## Success Criteria *(mandatory)* |
| 74 | + |
| 75 | +### Measurable Outcomes |
| 76 | + |
| 77 | +- **SC-001**: Disqus widget loads and displays correctly on all blog post pages |
| 78 | +- **SC-002**: No Commento-related network requests appear in browser DevTools |
| 79 | +- **SC-003**: Page load time does not increase significantly (Disqus async loading) |
| 80 | +- **SC-004**: Readers can successfully post comments via Disqus without errors |
| 81 | +- **SC-005**: Comment threading and reply functionality works correctly |
| 82 | +- **SC-006**: Site builds successfully with `hugo --gc --minify` after changes |
| 83 | +- **SC-007**: The migration completes without breaking existing site functionality |
0 commit comments