uui-pr-contributing

# UUI Pull Request Process Follow this checklist when preparing a pull request for UUI. ## Pre-PR Checklist Before opening a PR, ensure all items are complete: - [ ] **All tests pass** - Run `yarn test` - [ ] **Snapshots updated** - If UI changed, run `yarn test-update` - [ ] **E2E tests pass** - If UI changed, run `yarn test-e2e` - [ ] **ESLint passes** - Run `yarn eslint` (or `yarn eslint-fix`) - [ ] **Stylelint passes** - Run `yarn stylelint` (or `yarn stylelint-fix`) **Note:** Husky runs `lint-staged` on commit, which auto-fixes ESLint and Stylelint for staged files. You can still run lint manually to catch issues before committing. - [ ] **Bundle size check passes** - Run `yarn track-bundle-size` - [ ] **TypeScript type checking passes** - Run `yarn test-typecheck` - [ ] **Documentation updated** - If API changed, add examples and update Property Explorer - [ ] **Changelog updated** - Add entry to `changelog.md` ## Git Workflow ### Branch Creation 1. **Fork and clone** the repository 2. **Create branch from `develop`** (not `main`): ```bash git checkout develop git pull origin develop git checkout -b fix/123-description ``` ### Branch Naming Use descriptive branch names following these patterns: **For bug fixes:** - `fix/123-dropdown-position` - Include GitHub issue number - `fix/dropdown-position` - If no issue number **For features:** - `feature/456-new-component` - Include GitHub issue number - `feature/new-component` - If no issue number **For other changes:** - `refactor/component-structure` - `docs/update-readme` **Important:** When working on features or bugs from GitHub issues, **include the issue number** in the branch name (e.g., `fix/123-description`, `feature/456-new-component`). **Avoid generic names:** - ❌ `update` - ❌ `fix` - ❌ `changes` ## Commit Messages - Use clear, descriptive commit messages - Reference issue numbers when applicable: `fix: resolve dropdown positioning issue (#123)` - Follow conventional commit format when possible: - `feat: add new component` - `fix: correct date formatting` - `docs: update README` - `refactor: simplify component logic` - **Before committing:** Always show the proposed commit message to the user and wait for approval before running `git commit`. Do not commit automatically. - **Shell compatibility:** Do not use bash-only syntax (heredoc `<<'EOF'`, `&&` chaining). Use multiple `-m` flags for multi-line commits: ```bash git commit -m "subject line" -m "body line 1" -m "body line 2" ``` ## PR Requirements ### Code Quality - **All tests must pass** (`yarn test`) - **Bundle size check must pass** (`yarn track-bundle-size`) - **E2E tests must pass** (if UI changes) - **Code must be linted** (`yarn eslint`, `yarn stylelint`) ### Documentation If making API changes or adding functionality: 1. **Add example** to documentation: - Location: `app/src/docs/_examples` - Add link in page config: `app/src/docs/pages` 2. **Update Property Explorer**: - Location: `app/src/docs/explorerConfigs` - Add/update explorer config for component 3. **Add JSDoc** on every new/changed exported type and non-inherited public prop. The quality gate fails if the amount of props without comments increases (see [documentation](../documentation/SKILL.md#jsdoc-comments-required)). 4. **Generate API**: ```bash yarn generate-components-api ``` ### Changelog Add entry to the top (unreleased) section of `changelog.md`: ```markdown # 6.x.x - xx.xx.2026 **What's New** * [ComponentName]: description of new feature ([#456](https://github.com/epam/UUI/issues/456)) **What's Fixed** * [ComponentName]: description of fix ([#123](https://github.com/epam/UUI/issues/123)) ``` **Format:** - Use `**What's New**` for features/enhancements, `**What's Fixed**` for bug fixes - Prefix with `[ComponentName]:` to identify the affected component - Include issue link in markdown format: `([#123](https://github.com/epam/UUI/issues/123))` - Add to the existing top section; do not create a new version header ## PR Process Steps 1. **Fork and clone** the repository 2. **Create branch from `develop`** (include GitHub issue number if applicable) 3. **Make changes** following development guides 4. **Add tests** (unit and E2E where appropriate) 5. **Ensure test suite passes** (`yarn test`), update snapshots if needed 6. **Run E2E/screenshot tests** if making UI changes 7. **If making API changes:** - Add example to documentation - Update Property Explorer 8. **Add short description** to `changelog.md` 9. **Commit and push** to your fork 10. **Open PR** targeting `develop` branch ## PR Description Template When opening a PR, include: - **Summary** - Brief description of changes - **Issue** - Link to GitHub issue (if applicable) - **Type** - Bug fix, Feature, Refactor, Docs, etc. - **Testing** - How to test the changes - **Checklist** - Confirm all PR requirements met ## Quality Gates PRs must pass these quality checks: 1. ✅ All tests pass 2. ✅ Bundle size check passes 3. ✅ E2E tests pass (if UI changes) 4. ✅ Code is linted 5. ✅ Documentation updated (if API changes) 6. ✅ Changelog updated ## Common Issues ### Bundle Size Check Fails If bundle size increased intentionally: ```bash yarn track-bundle-size-override ``` **Warning:** Only use if sizes are expected to increase. This overrides the baseline. ### Tests Fail on Windows Use reduced worker count: ```bash yarn test --maxWorkers=2 --testTimeout=10000 ``` You can increase `maxWorkers` up to 4 if needed. ### E2E Tests Fail 1. Ensure server is running (`yarn start` or `yarn build-server && yarn start-server`) 2. Check `.env` file for `UUI_APP_BASE_URL` if using non-standard URL 3. Update screenshots if intentional: `yarn test-e2e-update` ### App Won't Start 1. Run `yarn` and `cd server && yarn` to install all dependencies 2. Run `yarn build-server` before `yarn start` 3. Ensure port 9009 is free. If occupied, set `PORT` env var or stop the conflicting process ### Run Single Test File ```bash yarn test -- --testPathPattern="Button" ``` Use `--testNamePattern="should render"` to match test names. See [unit-testing](../unit-testing/SKILL.md) for more. ## References - Main guidelines: [AGENTS.md](../AGENTS.md) Section 7 - Contributing guide: [CONTRIBUTING.md](../../CONTRIBUTING.md) - E2E testing: [.cursor/skills/e2e-testing/SKILL.md](../e2e-testing/SKILL.md) - Unit testing: [.cursor/skills/unit-testing/SKILL.md](../unit-testing/SKILL.md)