docs(v0.9.5): Add release notes and post-mortem

hangtime79 · claude · hangtime79 · commit 5ce14f218dd8 · 2025-12-29T00:21:00.000+11:00
- Release notes for v0.9.5 - Post-mortem analysis - Updated CHANGELOG - Updated CLAUDE.md with new gotchas and roadmap 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.5] - 2025-12-29
+
+### Added
+- Dependency tooltips now show task names instead of IDs (#65)
+  - Automatic name lookup with fallback to ID for missing references
+- Pin tooltip feature to keep tooltips visible while exploring chart (#68)
+  - Pin button (thumbtack icon) in tooltip header
+  - Multiple tooltips can be pinned simultaneously
+  - Collision avoidance prevents overlap between tooltips
+  - Close button or pin toggle to dismiss
+
 ## [0.9.4] - 2025-12-28
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -58,6 +58,8 @@ DSS Dataset → backend.py → TaskTransformer → dependency_validator → JSON
 - **Grid header is HTML, not SVG** — `.grid-header` is an HTML `<div>` with absolutely-positioned text divs, NOT an SVG group. Header decorations (separators, etc.) must use HTML elements, not SVG lines.
 - **Position-based date lookup** — When adding year to upper header text post-render, DON'T search `ganttInstance.dates` by month name (`dates.find(d => d.getMonth() === monthNum)`) — this finds the FIRST match regardless of position. Instead, use index lookup: `dates[Math.round(elementX / columnWidth)]` to get the exact date at that element's position.
 - **Frappe Gantt popup positioning** — Library treats popup coords as anchors and re-centres vertically after render. Don't fight it by modifying `opts.x/y` before calling `show_popup()`. Instead: call `originalShowPopup(opts)` first, then correct position in `requestAnimationFrame()` by directly setting `popup.style.left/top`. Disable transition temporarily to prevent visual jump.
+- **Webapp icons require inline SVG** — FontAwesome classes (`fas fa-*`) don't work in Dataiku webapp context. Use inline SVG with `fill="currentColor"` for theme compatibility. FontAwesome is only available for `plugin.json` icon field.
+- **Frappe Gantt single popup** — Library has single `$popup_wrapper`. For multiple simultaneous tooltips, clone popup content into independent DOM elements in a separate container.
 
 ---
 
@@ -139,7 +141,7 @@ Simple fixes with plenty of context don't need intervention tracking.
 - [Release](https://github.com/hangtime79/dss-plugin-gantt-chart/releases/tag/v0.9.4)
 - [PR #73](https://github.com/hangtime79/dss-plugin-gantt-chart/pull/73)
 
-**Next Milestone:** v0.9.5 - Tooltip Polish II (#65, #68)
+**Next Milestone:** v0.9.6 - Visual Enhancements (#49, #57)
 
 **Backlog:** [GitHub Issues](https://github.com/hangtime79/dss-plugin-gantt-chart/issues)
 **Upstream Bugs:** `plan/frappe-gantt-upstream-bugs.md`
@@ -159,12 +161,12 @@ Simple fixes with plenty of context don't need intervention tracking.
 | ~~**v0.9.2**~~ | ~~#62, #63, #64~~ | ~~Visual Polish II~~ ✅ |
 | ~~**v0.9.3**~~ | ~~#71~~ | ~~Bug Fix: Header Contrast~~ ✅ |
 | ~~**v0.9.4**~~ | ~~#66, #67~~ | ~~Tooltip Polish I (Positioning & Appearance)~~ ✅ |
-| **v0.9.5** | #65, #68 | Tooltip Polish II (Content & Interaction) |
+| ~~**v0.9.5**~~ | ~~#65, #68~~ | ~~Tooltip Polish II (Content & Interaction)~~ ✅ |
 | **v0.9.6** | #49, #57 | Visual Enhancements |
 | **v0.9.7** | #60 | Reset Zoom |
 | **v0.9.8** | #51 | Task Filtering |
 | **v0.10.0** | #32 | i18n |
 | **v1.0.0-rc** | #24, #25 | Print + Global Params (TBD) |
 | **v1.0.0** | — | Public Release |
 
-**Current milestone:** v0.9.5 - Tooltip Polish II (#65, #68)
+**Current milestone:** v0.9.6 - Visual Enhancements (#49, #57)
diff --git a/plan/post-mortems/v0.9.5-post-mortem.md b/plan/post-mortems/v0.9.5-post-mortem.md
@@ -0,0 +1,106 @@
+# Post-Mortem: v0.9.5
+
+**Branch:** `feature/v0.9.5-tooltip-polish-ii`
+**Type:** Feature
+**Duration:** 1 day (Started: 2025-12-29, Completed: 2025-12-29)
+**Outcome:** ✅ Success
+
+---
+
+## Summary
+
+Implemented two tooltip enhancements: dependency name resolution (showing task names instead of IDs) and a pinnable tooltip system. The pin feature evolved during QA from single-pinned to multi-pinned with collision avoidance based on user feedback.
+
+---
+
+## Scope
+
+### Planned
+- [x] Show task names in dependency tooltips (#65)
+- [x] Pin tooltip to keep visible (#68)
+
+### Delivered
+- [x] Dependency name resolution with fallback to ID
+- [x] Multi-pinned tooltip system (enhanced from original spec)
+- [x] Collision avoidance for overlapping tooltips
+- [x] Pin/unpin toggle with visual indicator
+
+### Deferred Items
+None
+
+---
+
+## Commit Analysis
+
+| Metric | Value | Assessment |
+|--------|-------|------------|
+| Total commits | 1 | Squashed during development |
+| Feature commits | 1 | |
+| Fix/debug commits | 0 | |
+| Reverts | 0 | |
+| Churn ratio | 0% | 🟢 Low |
+
+---
+
+## What Went Well
+
+- **Clean Python implementation**: Dependency name resolution was straightforward - simple post-processing loop after task creation
+- **Iterative QA refinement**: User feedback during QA led to better multi-tooltip design
+- **Inline SVG for icons**: Learned from v0.9.1 post-mortem that FontAwesome doesn't work in Dataiku webapp context - used inline SVG from start
+
+---
+
+## What Didn't Go Well
+
+- **Initial pin design too simple**: Original spec assumed single-pinned tooltip, but user clarified they wanted multiple simultaneous tooltips
+- **FontAwesome assumption**: Initially tried `fas fa-thumbtack` class before remembering Dataiku context requires inline SVG
+
+---
+
+## Blockers Encountered
+
+| Blocker | Impact | Resolution | Time Lost |
+|---------|--------|------------|-----------|
+| FontAwesome icons not rendering | Icons invisible in tooltip | Switched to inline SVG paths | ~15 min |
+| Single vs multi-tooltip design | Had to redesign pin system | Created clone-based pinned container | ~30 min |
+
+---
+
+## Technical Discoveries
+
+### Platform Behavior
+- Dataiku webapps don't have FontAwesome 5 class support despite it being available for plugin.json icons
+
+### Library Behavior
+- Frappe-gantt has single `$popup_wrapper` - supporting multiple tooltips requires creating independent DOM elements
+
+### Architecture Insights
+- Clone-based approach for pinned tooltips cleanly separates library-managed popup from user-pinned copies
+- Using `pointer-events: none` on container with `pointer-events: auto` on children allows click-through while keeping tooltips interactive
+
+---
+
+## CLI Docs Candidates
+
+1. **Inline SVG for webapp icons**: FontAwesome classes don't work in Dataiku webapp context. Use inline SVG with `fill="currentColor"` for theme compatibility.
+
+---
+
+## Recommendations
+
+### For Next Release
+- Consider adding keyboard shortcuts for pin/close (Escape to close all pinned)
+
+### Process Improvements
+- Clarify multi-element behaviors upfront in QA script
+
+### Technical Debt
+- None introduced
+
+---
+
+## Lessons Learned
+
+1. **Clarify "pin" semantics early**: Single vs multiple pinned items is a fundamental UX decision that affects architecture
+2. **Reuse prior learnings**: The FontAwesome-in-SVG issue was already documented in v0.9.1 post-mortem
+3. **Clone-based persistence**: When a library manages a singleton element, cloning is cleaner than fighting the library's lifecycle
diff --git a/plan/releases/v0.9.5-release-notes.md b/plan/releases/v0.9.5-release-notes.md
@@ -0,0 +1,76 @@
+# Release Notes: v0.9.5
+
+**Release Date:** 2025-12-29
+**Type:** Feature
+**Branch:** `feature/v0.9.5-tooltip-polish-ii`
+
+---
+
+## Summary
+
+This release enhances tooltip usability with two key improvements: dependency tooltips now show human-readable task names instead of cryptic IDs, and users can pin multiple tooltips to keep them visible while exploring the chart.
+
+---
+
+## Changes
+
+### Added
+- **Dependency Name Resolution (#65)**: Tooltip "Depends on" field now shows task names instead of raw IDs
+  - Automatic lookup of dependency IDs to task names
+  - Fallback to ID if dependency references external/missing task
+- **Pin Tooltip Feature (#68)**: Users can pin tooltips to keep them visible
+  - Pin button (thumbtack icon) in tooltip header
+  - Multiple tooltips can be pinned simultaneously
+  - Pinned tooltips persist until explicitly closed
+  - Collision avoidance prevents new tooltips from overlapping pinned ones
+  - Close button (X) or clicking highlighted pin removes tooltip
+
+---
+
+## Files Modified
+
+| File | Change Type | Description |
+|------|-------------|-------------|
+| `python-lib/ganttchart/task_transformer.py` | Modified | Added post-processing to resolve dependency IDs to names |
+| `webapps/gantt-chart/app.js` | Modified | Added pinned tooltip system with collision avoidance |
+| `resource/webapp/style.css` | Modified | Added styles for pinned tooltips container and buttons |
+| `plugin.json` | Modified | Version 0.9.4 → 0.9.5 |
+| `plan/specs/feature-v0.9.5-spec.md` | Added | Feature specification |
+
+---
+
+## Testing
+
+- **Unit Tests:** 122/122 passing
+- **Manual Verification:**
+  - [x] Dependency names show in tooltip instead of IDs
+  - [x] Pin button visible and functional
+  - [x] Multiple tooltips can be pinned
+  - [x] Collision avoidance works
+  - [x] Close/unpin buttons work
+  - [x] Dark mode styling correct
+
+---
+
+## Breaking Changes
+
+None
+
+---
+
+## Known Issues
+
+None
+
+---
+
+## Dependencies
+
+None
+
+---
+
+## Related Documents
+
+- Spec: `plan/specs/feature-v0.9.5-spec.md`
+- Post-mortem: `plan/post-mortems/v0.9.5-post-mortem.md`
