freemium-survey-components 2.0.479 → 2.0.481

package/.github/pr_validation_guide.md

@@ -0,0 +1,305 @@
+# PR Validation Guide
+
+This document explains how PR validation works in the `freemium-survey-components` repository.
+
+## Overview
+
+Validation happens in two layers:
+
+```text
+┌──────────────────────┬─────────────────────────────────────┬─────────────────────┐
+│ Layer                │ What It Validates                   │ When                │
+├──────────────────────┼─────────────────────────────────────┼─────────────────────┤
+│ Git Hooks (Local)    │ Commit message format (fail-fast)   │ On commit           │
+│                      │ Lint, format, install, build        │ On commit           │
+├──────────────────────┼─────────────────────────────────────┼─────────────────────┤
+│ GitHub Actions       │ PR template completeness            │ On PR open/edit     │
+│                      │ Stale PR management                 │ Daily cron          │
+└──────────────────────┴─────────────────────────────────────┴─────────────────────┘
+```
+
+---
+
+## Local Validation — Git Hooks (Husky)
+
+### `.husky/pre-commit`
+
+Runs every time you commit, **before** the commit message is checked. Executes the quality & build chain:
+
+```text
+npm run lint    →   npm run format    →   npm install    →   npm run build
+```
+
+Any failure aborts the commit with a non-zero exit code.
+
+> The repo currently has no unit tests (only Storybook snapshot tests under `src/test/__snapshots__`), so `npm run test` is intentionally **not** part of the pre-commit chain. Add it back once unit tests exist.
+
+### `.husky/commit-msg`
+
+Runs after `pre-commit` passes. Validates only the commit message format — no lint/install/build work happens here.
+
+Required format:
+
+```text
+type: [TICKET-ID] message
+```
+
+- **Valid types:** `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, `style`, `revert`
+- **Valid tickets:** `MP-xxxx`, `FS-xxxx`, `FSURVEY-xxxx`, `DEVREL-xxxx`, `MISC`, `Docs`
+
+Examples:
+
+```text
+✅ feat: [FSURVEY-2024] Add Matrix question variant
+✅ fix: [MP-12345] Fix Dropdown keyboard navigation
+✅ chore: [MISC] Bump rollup version
+✅ docs: [Docs] Update Storybook README
+❌ Add matrix question                 (no type, no ticket)
+❌ feat: Add matrix question           (no ticket)
+❌ Feat: [MP-123] Add matrix           (type must be lowercase)
+```
+
+**Skipped automatically for:**
+
+- Merge commits (`Merge branch ...`, `Merge pull request ...`)
+- Revert commits (`Revert ...`)
+- Dependabot-style commits (`Bump X from Y to Z`)
+
+### Bypass (Emergency Only)
+
+```bash
+git commit --no-verify -m "..."
+```
+
+Skips all local hooks. Server-side PR validation will still enforce the title format on PR open.
+
+---
+
+## GitHub Actions Workflows
+
+### 1. PR Template Validation
+
+**File:** `.github/workflows/pr-template-validation.yml`
+
+**Triggers:** PR `opened`, `edited`, `synchronize`
+
+**Purpose:** Ensures the PR title and description follow the template contract. Posts a sticky validation comment and fails the check (blocks merge via branch protection) when required sections are missing.
+
+**Automated PRs are skipped** (Dependabot, Renovate, github-actions[bot], mergify[bot], snyk-bot, and any author ending in `[bot]`).
+
+#### 🔴 REQUIRED — Blocks merge if missing
+
+| #   | Check                        | Rule                                                                           |
+| --- | ---------------------------- | ------------------------------------------------------------------------------ |
+| 1   | PR Title                     | Must match `type: [TICKET-ID] description` with valid type and ticket          |
+| 2   | Type of Change               | At least one `- [x]` checked                                                   |
+| 3   | Ticket Reference             | PR body must contain `- **Ticket ID**: [FSURVEY-xxxx]` (or other valid prefix) |
+| 4   | Changes Made                 | At least **3** real bullet points (placeholders like `Change 1:` don't count)  |
+| 5   | Affected Areas               | At least one `- [x]` checked                                                   |
+| 6   | Breaking Changes             | Exactly one of "Yes" / "No" checked                                            |
+| 7   | Breaking Changes Description | If "Yes" selected, description must be > 50 characters                         |
+
+#### 🟡 RECOMMENDED — Warning only, does not block
+
+| #   | Check              | Rule                                                                                                                    |
+| --- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| 1   | Testing            | Numbered test steps with real content (not just `1. Step 1`)                                                            |
+| 2   | SDET Guidance      | > 30 chars of real content (placeholders stripped)                                                                      |
+| 3   | Screenshots/Videos | If `.tsx` files under `src/components/`, `src/survey/`, or `src/stories/` changed and no image/video URL in Screenshots |
+
+### 2. Stale PR Management
+
+**File:** `.github/workflows/stale.yml`
+
+**Triggers:** Daily cron (`0 0 * * *`) and manual dispatch.
+
+**Purpose:** Closes/labels stale PRs and issues to keep the backlog tidy.
+
+---
+
+## Validation Flow
+
+When you run `git commit`:
+
+```text
+.husky/pre-commit
+   └─ npm run lint → npm run format → npm install → npm run build
+.husky/commit-msg
+   └─ validate message format (fails fast if malformed)
+```
+
+When you open a PR:
+
+```text
+GitHub Actions:
+  └─ PR Template Validation    (sticky comment, can block merge)
+
+Manual:
+  └─ Code review approval
+```
+
+---
+
+## What Gets Checked Where
+
+| Check                      |   Local (Husky)   | GitHub Actions |
+| -------------------------- | :---------------: | :------------: |
+| Commit message format      | ✅ (`commit-msg`) |                |
+| Lint                       | ✅ (`pre-commit`) |                |
+| Format                     | ✅ (`pre-commit`) |                |
+| Unit tests                 |   ⏸️ (none yet)   |                |
+| Install                    | ✅ (`pre-commit`) |                |
+| Build (rollup)             | ✅ (`pre-commit`) |                |
+| PR title format            |                   |       ✅       |
+| Type of Change selected    |                   |       ✅       |
+| Ticket ID in body          |                   |       ✅       |
+| Changes Made (min 3)       |                   |       ✅       |
+| Affected Areas selected    |                   |       ✅       |
+| Breaking Changes selection |                   |       ✅       |
+| Breaking description (>50) |                   |       ✅       |
+| Testing info               |                   |   ⚠️ (warn)    |
+| SDET guidance              |                   |   ⚠️ (warn)    |
+| Screenshots for UI changes |                   |   ⚠️ (warn)    |
+
+---
+
+## How to Fix Validation Failures
+
+### Local: "Invalid commit message format!"
+
+The `commit-msg` hook rejected your message (this runs after `pre-commit`). Re-run with the correct shape:
+
+```bash
+git commit -m "feat: [FSURVEY-8530] Add Matrix question variant"
+```
+
+Since the message is preserved in `.git/COMMIT_EDITMSG`, re-running `git commit` (no `-m`) will reopen your editor with the previous content.
+
+### Local: Lint/format/install/build failed
+
+The `pre-commit` hook ran the quality chain and one step failed. Run the failing step directly to debug:
+
+```bash
+npm run lint
+npm run format
+npm install
+npm run build
+```
+
+### PR Template Validation Failed (GitHub Actions)
+
+1. Open the PR on GitHub → click **Edit** on the description
+2. Read the sticky "🔍 PR Template Validation Report" comment — it lists every failing check
+3. Fix the sections it flags. Common issues:
+   - **Ticket Reference missing:** Your body still has the placeholder `[FSURVEY-xxxx / MISC / Docs]`. Replace with the exact form: `- **Ticket ID**: [FSURVEY-8530]`
+   - **Changes Made insufficient:** Need at least 3 real bullets under `## Changes Made` — placeholders like `Change 1:` don't count
+   - **Breaking Changes:** Must check exactly one of Yes/No; both unchecked or both checked fails
+4. Save the PR description — the workflow re-runs automatically on the `edited` event
+
+### Common Gotchas
+
+| Symptom                                          | Cause                                                                                                                               |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Validation fails with valid-looking title        | PR title is lowercase `feat:` (correct) but ticket bracket has extra text like `[FSURVEY-8530 test]`                                |
+| "Ticket Reference missing" despite filling it in | The placeholder text `[FSURVEY-xxxx / MISC / Docs]` was not replaced with a real ticket like `[FSURVEY-8530]`                       |
+| Screenshot warning on non-visual PR              | Path-based detection — any `.tsx` under `src/components/`, `src/survey/`, or `src/stories/` triggers it even for pure logic changes |
+
+---
+
+## Best Practices
+
+### Before Committing
+
+Since the `pre-commit` hook runs lint/format/install/build, ensure they pass cleanly:
+
+```bash
+npm run lint
+npm run format
+npm install
+npm run build
+```
+
+### Writing a Good PR
+
+1. **Keep it focused** — small, single-purpose PRs review faster
+2. **Fill the template honestly** — at least 3 meaningful bullets under Changes Made
+3. **Describe "why", not just "what"** — the Motivation section is free-form for a reason
+4. **Add screenshots/videos / Storybook / Chromatic links** for any UI change (recommended, not enforced)
+5. **Fill SDET guidance** when the change has non-obvious edge cases
+
+### PR Description Checklist
+
+Before you submit:
+
+- ✅ Type of Change has at least one `[x]`
+- ✅ Ticket ID line shows `- **Ticket ID**: [FSURVEY-0000]` with the real number
+- ✅ Changes Made has 3+ real bullets
+- ✅ Affected Areas has at least one `[x]`
+- ✅ Breaking Changes has exactly one `[x]` (Yes or No)
+- ✅ If breaking Yes: description > 50 chars
+- ✅ Screenshots / Storybook / Chromatic link added for UI changes (recommended)
+- ✅ Testing & SDET Guidance filled (recommended)
+
+---
+
+## Troubleshooting
+
+### GitHub Actions doesn't run on my PR
+
+1. Check the **Actions** tab of the repo for errors
+2. Verify the workflow file is on the PR's base branch (not only the feature branch)
+3. Confirm the PR author isn't auto-classified as a bot (skip logic inspects `user.type` and login suffix `[bot]`)
+4. The workflow uses `secrets.RUNWAYCI_GITHUB_PAT_TOKEN` — if it's missing or expired, the validation step fails before running any check
+
+### Validation seems wrong
+
+1. Copy your exact PR description and inspect it against the regexes in `.github/workflows/pr-template-validation.yml`
+2. Remember: checkboxes must use `- [x]` (lowercase `x`), though the code is actually case-insensitive (`[X]` also works)
+3. Bold must be `**Ticket ID**:` exactly — no underscores, no extra spaces inside the `**`
+
+### Need to bypass validation
+
+- **Local hook:** `git commit --no-verify` (skips both `pre-commit` and `commit-msg`)
+- **PR template validation:** Cannot be bypassed without repo admin disabling the required status check — this is intentional
+
+---
+
+## Configuration
+
+To change validation rules:
+
+| File                                           | What to change                                                                   |
+| ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| `.github/workflows/pr-template-validation.yml` | Server-side template validation logic (regexes, thresholds, required vs warning) |
+| `.github/pull_request_template.md`             | The template users see when opening a PR                                         |
+| `.husky/commit-msg`                            | Local commit message format validation                                           |
+| `.husky/pre-commit`                            | Local lint / format / install / build chain                                      |
+
+### Ticket Prefix Changes
+
+Valid ticket prefixes are defined in **two** places and must stay in sync:
+
+- `.husky/commit-msg` — regex `ticket_pattern` around line 30
+- `.github/workflows/pr-template-validation.yml` — `titleRegex` (line ~100) and `ticketRegex` (line ~137)
+
+---
+
+## Summary
+
+This system enforces:
+
+- ✅ Consistent commit messages (local, fail-fast)
+- ✅ Compilable, linted, formatted code (local, before commit)
+- ✅ Complete PR descriptions with traceability to a ticket (GitHub Actions)
+
+All automated — fill the PR template properly and use the commit format, and the checks will pass.
+
+---
+
+## Related Files
+
+- [Pull Request Template](./pull_request_template.md)
+- [PR Template Validation Workflow](./workflows/pr-template-validation.yml)
+- [Stale PR Workflow](./workflows/stale.yml)
+- [Husky commit-msg Hook](../.husky/commit-msg)
+- [Husky pre-commit Hook](../.husky/pre-commit)

package/.github/pull_request_template.md

@@ -0,0 +1,189 @@
+<!---
+📋 PR Template Guidelines:
+- PR TITLE must follow format: type: [TICKET-ID] description
+  Example: feat: [MP-12345] Add Matrix question variant · feat: [FS-12345] for FS tickets
+- Sections marked with ⚠️ REQUIRED will be validated by GitHub Actions
+- Sections marked with ⚠️ RECOMMENDED should be filled for better reviews
+- Incomplete required sections will block PR merge
+- See .github/workflows/pr-template-validation.yml for validation rules
+-->
+
+## Type of Change ⚠️ REQUIRED
+
+<!--- REQUIRED: Put an `x` in at least ONE box that applies -->
+<!--- This should match your commit message type (feat/fix/chore/docs/etc.) -->
+
+- [ ] Feature (new functionality)
+- [ ] Bugfix (fixes an issue)
+- [ ] Refactor (code improvement without changing functionality)
+- [ ] Maintenance (dependency updates, chores)
+- [ ] Performance (optimization)
+- [ ] Documentation (content or code documentation updates)
+- [ ] Security (security fixes or improvements)
+- [ ] Configuration (build, CI/CD, or tooling changes)
+
+## Ticket Reference ⚠️ REQUIRED
+
+<!--- REQUIRED: Link to the related ticket or story -->
+
+- **Ticket ID**: [FSURVEY-xxxx / MISC / Docs]
+- **Ticket Link**: [Link to Freshrelease story or issue]
+
+## Motivation
+
+<!--- Why is this change required? What problem does it solve? -->
+<!--- If it fixes an open issue, please link to the freshrelease story here or ensure the id is in the PR title. -->
+<!--- Please ensure that you have run all lints related to this repo and also ensure that your PR is small enough for quick review. -->
+
+## Changes Made ⚠️ REQUIRED
+
+<!--- REQUIRED: Provide a clear description of what you changed -->
+<!--- REQUIRED: List at least 3 main changes in bullet points -->
+
+- Change 1:
+- Change 2:
+- Change 3:
+
+## Affected Areas ⚠️ REQUIRED
+
+<!--- REQUIRED: Put an `x` in at least ONE box that applies -->
+
+- [ ] Source (`src`)
+- [ ] Build / Bundling (`rollup.config.ts`, `scripts/`, `tsconfig.json`, `postcss.config.js`)
+- [ ] CI/CD workflows (`.github/workflows`)
+- [ ] Dependencies (`package.json`)
+
+## Breaking Changes ⚠️ REQUIRED
+
+<!--- REQUIRED: Select one option -->
+
+- [ ] Yes, this PR introduces breaking changes
+- [ ] No breaking changes
+
+<!--- REQUIRED if Yes: Describe the breaking changes (API changes, removed props, renamed components, version-bump impact) and migration steps below -->
+
+## Checklist
+
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+
+### Code Quality
+
+- [ ] My code follows the code style of this project
+- [ ] I have run `npm run lint` and fixed all errors
+- [ ] I have run `npm run format` to format the code
+- [ ] No console.log or debugging code left in the changes
+  - Format: `type: [TICKET-ID] message`
+  - Valid types: feat, fix, chore, docs, refactor, test, perf, ci, build, style, revert
+  - Valid tickets: FSURVEY-xxxx / MISC / Docs
+
+### Testing
+
+- [ ] I have verified the component visually in Storybook (`npm run storybook`)
+- [ ] I have reviewed the Chromatic diff (if applicable)
+- [ ] I have tested on multiple browsers (if UI changes)
+- [ ] Storybook snapshot tests pass (`npm run test-storybook`)
+- [ ] I have tested the production bundle (`npm run build`)
+
+### Documentation
+
+- [ ] My change requires a change to the documentation
+- [ ] I have updated the documentation / Storybook stories accordingly
+- [ ] I have updated code comments where necessary
+- [ ] I have added JSDoc comments for new functions/components
+
+### Accessibility & Security
+
+- [ ] I have tested keyboard navigation (if UI changes)
+- [ ] I have verified ARIA labels and semantic HTML (if UI changes)
+- [ ] I have validated component props (required vs optional, defaults)
+- [ ] I have checked for security vulnerabilities (`npm audit`)
+
+### Dependencies
+
+- [ ] I have added new dependencies (list them below)
+- [ ] I have updated existing dependencies (list them below)
+- [ ] I have verified dependency compatibility with existing peer dependencies
+- [ ] I have checked for security vulnerabilities in new dependencies
+
+<!--- List new or updated dependencies here -->
+
+**New/Updated Dependencies:**
+
+-
+-
+
+## How Has This Been Tested? ⚠️ RECOMMENDED
+
+<!--- RECOMMENDED: Describe in detail how you tested your changes -->
+<!--- Include details of your testing environment and test steps -->
+
+**Testing Environment:**
+
+- Node version:
+- npm version:
+- Browser(s) tested:
+
+**Test Steps:**
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Test Results:**
+
+- Result 1
+
+## Screenshots/Videos ⚠️ REQUIRED FOR UI CHANGES
+
+<!--- REQUIRED for UI changes: Add screenshots, videos, or a Storybook / Chromatic link to demonstrate the changes -->
+<!--- REQUIRED: Include before/after screenshots for visual changes -->
+
+**Before:**
+
+**After:**
+
+## Performance Impact
+
+<!--- Describe any performance implications of this change -->
+
+- [ ] No performance impact
+- [ ] Performance improvement (describe below)
+- [ ] Potential performance impact (describe below)
+
+<!--- If applicable, include bundle size changes, build time changes, etc. -->
+
+## Deployment / Release Notes
+
+<!--- Any special publish considerations? -->
+<!--- Version bump type (patch/minor/major), consumer migration, peer-dep updates, etc. -->
+
+- [ ] No special release steps required
+- [ ] Requires a specific version bump (patch / minor / major — describe below)
+- [ ] Requires consumer migration (describe below)
+
+## What should the SDET know? ⚠️ RECOMMENDED
+
+<!--- RECOMMENDED: Provide testing guidance for QA team -->
+<!--- Include test scenarios, edge cases, and areas to focus on -->
+
+- Test scenario 1:
+- Edge case to check:
+- Focus area:
+
+## Additional Context
+
+<!--- Add any other context, links, or information that reviewers should know -->
+<!--- Related PRs, design documents, API documentation, etc. -->
+
+## Reviewer Checklist
+
+<!--- For reviewers - ensure these are verified -->
+
+- [ ] Code changes align with the motivation and description
+- [ ] No unnecessary files or changes included
+- [ ] Code follows project conventions and style guide
+- [ ] Stories / snapshots are adequate and passing
+- [ ] Documentation is updated if needed
+- [ ] No security vulnerabilities introduced
+- [ ] Performance / bundle-size impact is acceptable