diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 0000000000..265fd779f9 --- /dev/null +++ b/.cursor/README.md @@ -0,0 +1,59 @@ +# Cursor rules documentation + +This directory contains rules that Cursor uses to enforce consistent formatting and structure in our codebase. + +## Rule structure + +Rules defined in the `config.json` follow this structure: + +```json +{ + "version": 1, + "rules": { + "category": { + "rule_name": { + "enabled": true, + "pattern": "regex_pattern", + "message": "Error message" + } + } + } +} +``` + +Additional, more specific rules can be found in the `rules` directory in either a `json` or `mdc` format. + +## Available rules + +### Text formatting + +- **heading_case**: Enforces sentence case in headings with specific exceptions + - Applies to: `.md`, `.txt`, `.mdx` files + - Exceptions: Technical terms and acronyms + +### Jira tickets + +- **ticket_title**: Validates Jira ticket title format + - Optional component in brackets + - Max length: 80 characters +- **required_sections**: Ensures required sections are present +- **templates**: Enforces template structure for different ticket types +- **labels**: Validates that only allowed labels are used +- **issue_types**: Ensures correct issue type selection + +## Usage + +1. Cursor will automatically enforce these rules while editing relevant files; however, if you wish to enable a rule that is not triggered by default, you can do so by `@` mentioning it in the chat. +2. Rules can be toggled using the `enabled` flag +3. Custom error messages will be shown when rules are violated +4. Exceptions are handled through the `exceptions` field in relevant rules + +## Updating rules + +To modify these rules: + +1. Edit the `config.json` or the appropriate file in the `rules` directory +2. Try to follow the existing structure and format where possible +3. Ensure valid regex patterns, where applicable +4. Include clear error messages +5. Test changes before committing diff --git a/.cursor/config.json b/.cursor/config.json new file mode 100644 index 0000000000..a852662510 --- /dev/null +++ b/.cursor/config.json @@ -0,0 +1,148 @@ +{ + "text_formatting": { + "headings": { + "case": "sentence", + "files": ["**/*.md", "**/*.txt", "**/*.mdx"], + "message": "Use sentence case (capitalize only the first word and proper nouns/acronyms)", + "inline": true + }, + "patterns": ["**/*.md", "**/*.txt", "**/*.mdx"] + }, + "jira_tickets": { + "title_format": { + "pattern": "^\\[?[A-Za-z0-9-]+\\]?\\s.+$", + "max_length": 80 + }, + "required_sections": ["Acceptance case", "Overview"], + "labels": { + "a11y": "Accessibility issues", + "API": "Component API changes", + "docs": "Documentation updates", + "engineering-processes": "Engineering workflow improvements", + "feature": "New features", + "hold": "Suspended tickets", + "i18n": "Internationalization work", + "iOS": "iOS-specific issues", + "mobile": "Mobile platform issues", + "necromancy": "Old backlog tickets (>2 years)", + "product-processes": "Product team process improvements", + "refactor": "Code restructuring", + "research": "Investigation tasks", + "RFC": "Request for Comments", + "s2foundations": "S2 Foundations work", + "spectrum2": "Spectrum 2 tasks", + "team-processes": "Team workflow improvements", + "testing": "Test implementation", + "triage": "Needs assessment", + "VoiceOver": "VoiceOver specific issues" + }, + "issue_types": ["Bug", "Epic", "Story", "Task"], + "templates": { + "bug": { + "required_fields": [ + "Expected behaviour", + "Actual behaviour", + "Reproduction steps", + "Severity" + ] + }, + "feature": { + "required_fields": ["Overview", "Acceptance criteria"], + "optional_fields": [ + "Estimated internal impact", + "Estimated external impact", + "Anticipated reviewing audience", + "Proposed solutions", + "Supplementary documentation" + ] + } + } + }, + "git": { + "branchNameTemplate": "{username}/{type}-{description}{?-{issue}}", + "types": [ + "feat", + "fix", + "docs", + "style", + "refactor", + "perf", + "test", + "build", + "ci", + "chore", + "revert" + ], + "promptForIssueNumber": true, + "allowEmptyIssueNumber": true, + "transformDescription": "lowercase-dashed", + "validationPattern": "^[a-z0-9]+\\/(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)-[a-z0-9-]+(-swc-[0-9]+)?$", + "validationMessage": "Branch name should follow format: username/type-description[-swc-issue]" + }, + "editor": { + "formatOnSave": true, + "defaultFormatter": "prettier", + "tabSize": 4, + "insertSpaces": true, + "endOfLine": "auto", + "charset": "utf-8" + }, + "language": { + "typescript": { + "formatOnSave": true, + "organizeImportsOnSave": true, + "addMissingImports": "prompt", + "defaultFormatter": "eslint" + }, + "javascript": { + "formatOnSave": true, + "organizeImportsOnSave": true, + "addMissingImports": "prompt", + "moduleResolution": "auto", + "snippets": { + "newScript": { + "detectModuleFormat": true, + "preferESM": true + } + } + }, + "css": { + "formatOnSave": true, + "defaultFormatter": "stylelint" + } + }, + "terminal": { + "defaultProfile": "${os.shell}", + "integrated": { + "fontFamily": "${os.monospace}", + "fontSize": 12, + "shell": { + "windows": "powershell.exe", + "linux": "bash", + "osx": "bash" + } + } + }, + "search": { + "exclude": { + "**/node_modules": true, + "**/dist": true, + "**/.git": true, + "**/.vs": true, + "**/.idea": true, + "**/*.css.js": true, + "**/*.css.ts": true, + "**/*.d.ts": true, + "**/coverage": true, + "**/.wireit": true, + "**/*.tsbuildinfo": true, + "**/custom-elements.json": true, + "**/test/benchmark/results": true, + "**/storybook-static": true, + "**/*.min.*": true, + "**/*.map": true + }, + "useGitIgnore": true, + "followSymlinks": false + } +} diff --git a/.cursor/rules/branch-naming.mdc b/.cursor/rules/branch-naming.mdc new file mode 100644 index 0000000000..288e704f69 --- /dev/null +++ b/.cursor/rules/branch-naming.mdc @@ -0,0 +1,53 @@ +--- +description: +globs: +alwaysApply: true +--- +# Branch naming format + +Suggests the ideal branch naming format for Spectrum Web Components contributions. + +## Pattern +``` +^[a-z0-9]+\/(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)-[a-z0-9-]+(-swc-[0-9]+)?$ +``` + +## Message +Consider following the preferred branch naming format: `/-[-swc-]` + +Username will be automatically pulled from your git config settings. + +### Guidelines +- Use lowercase letters and numbers only +- Separate words with dashes (not camelCase) +- Use conventional commit types: + • **feat**: New feature + • **fix**: Bug fix + • **docs**: Documentation only + • **style**: Code style/formatting + • **refactor**: Code change that neither fixes a bug nor adds a feature + • **perf**: Code change that improves performance + • **test**: Adding missing tests or correcting existing tests + • **build**: Changes that affect the build system or external dependencies + • **ci**: Changes to CI configuration files and scripts + • **chore**: Other changes that don't modify src or test files + • **revert**: Reverts a previous commit +- Optional issue number format: `-swc-XXX` + +### Good examples +- `johndoe/feat-add-new-button-swc-123` +- `janedoe/fix-dropdown-alignment` +- `alice/refactor-component-structure` +- `bob/perf-optimize-rendering` + +### Avoid +- `johnDoe/feat-addNewButton` (no camelCase) +- `jane/fix-Dropdown-Bug` (no uppercase) + +This is a recommended format to maintain consistency, but not required. + +## Severity +warning + +## Scope +git_branch diff --git a/.cursor/rules/jira-ticket.mdc b/.cursor/rules/jira-ticket.mdc new file mode 100644 index 0000000000..59ba9ad035 --- /dev/null +++ b/.cursor/rules/jira-ticket.mdc @@ -0,0 +1,180 @@ +--- +description: Guidelines for drafting and formatting Jira tickets +globs: **/*.md, **/*.txt +alwaysApply: false +--- + +# Jira ticket guidelines + +## Title format + +- Use the format: `[Component] Brief description of change or issue` +- Keep titles concise but descriptive (under 80 characters) +- Use present tense for the description (e.g., "Add" not "Added") + +## Description structure + +All tickets must include acceptance criteria. + +- Include a link to any GitHub pull requests or RFCs, if they exists. Prompt for the link if it's not provided. +- When writing the description, include as much information as you can so that the objective of the ticket is clear. Anyone should be able to pick up the issue without needing a kickoff session. + +If it's applicable, please try to include a prefix in your JIRA ticket title the way we would in Commitlint to make it easy to identify the type of task. + +(component) is optional, especially if the ticket involves multiple components, and the exact syntax may vary. Do I need to use brackets or parentheses? What about capitalization? Don't worry about it. It's not like these will go into the commit history. + +Some prefix ideas and potential variations (besides brackets bc Confluence doesn't like them, apparently): + +Bug(component): / bug: / Fix(component): / fix: +Docs(component): / docs: / Documentation: +Feat(component): / feat: +Refactor(component): +Research(component): / discovery: / RFC(component): +S2 Foundations: / S2: +Test(component): + +More specific templates: + +### General Jira ticket template + +**Acceptance criteria** +(how we ensure that the work is complete) + +**Overview** +(plain language explaining the ticket) + +**Technical notes/resources** +(any technical notes/links/etc) + +**QA** +(steps someone will use to be sure that the work fulfills the ticket's request and that everything's working properly) + +**Design specs** +(are there any design specs/files/mock-ups we can include here? Any other design notes?) + +### Bug reporting template + +**Link to original issue** +(Add a link to the original issue in GitHub if applicable) + +**Expected behavior** +(Description of what the user would expect to happen) + +**Actual behavior** +(The actual behavior observed by the user) + +**Screenshots** +(Screenshots of the problem if applicable) + +**How can we reproduce the issue?** + +1. Go to '...' +2. Click on '....' +3. Scroll to '....' +4. Check console +5. See error + +**Sample code or abstract reproduction which illustrates the problem** +(are there any design specs/files/mock-ups we can include here? Any other design notes?) + +**Severity** +(The severity of the issue according to the [documentation](mdc:https:/github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTING.md#issue-severity-classification)) + +### RFC or feature ticket template + +This ticket template is for tracking work for RFCs, new features, new components, or research tickets. This template is not a substitute for the deliverable itself; rather, it's setting expectations for what the deliverable might look like and gives a high-level overview of the problem being tackled so that others can understand what is being worked on. + +Items with an asterisk are optional depending on the context. + +**Link to original issue** +(Add a link to the original issue in GitHub if applicable) + +**Overview** +(The problem you're looking to explore solutions for or do research on) + +**Acceptance Criteria** +(What is the desired outcome of this RFC or research process? What would make this ticket "done"? What follow-up work would be required? Refer to the RFC guide for examples.) + +**Estimated internal impact\*** +(If implemented, what impact would this work have on other APIs, other components, the project structure, or team initiatives? Refer to the impact diagram for details.) + +**Estimated external impact\*** +(If implemented, what impact would this work have on consumers or downstream/upstream dependencies?) + +**Anticipated reviewing audience\*** +(Who would you like to provide feedback on your RFC/research? Your immediate team, your partners, or a wider consumer audience? What are their roles?) + +**Proposed solutions\*** +(Pseudocode or short description that outlines what the solution might look like. You may not have any solutions yet.) + +**Supplementary documentation\*** +(Has this feature or component been implemented in existing design specs or in another project? Share those here to paint a bigger picture of the end result. For architectural changes, have you seen this done in other libraries? Are there any tools you're looking at trying out to solve your problem?) + +**Additional Context** +(Add any other context, drafts, etc. if you have them) + +## Severity classification + +- SEV1: Critical - System down, data loss, security breach +- SEV2: High - Major feature broken, significant user impact +- SEV3: Medium - Feature partially broken, moderate impact +- SEV4: Low - Minor issues, minimal user impact +- SEV5: Trivial - Cosmetic issues, no functional impact + +## Best practices + +- Link to relevant GitHub issues or pull requests using the format: `GH-{number}` +- Include component name in brackets if applicable: `[sp-button]` +- Add relevant labels for easier filtering +- Attach screenshots or videos for visual changes +- Reference design specs or documentation when available + +## Acceptance criteria + +- Write criteria in "Given/When/Then" format +- Make criteria specific and testable +- Include edge cases and error scenarios +- Consider accessibility requirements + +## Comments and updates + +- Keep comments focused and constructive +- Update ticket status promptly +- Document important decisions or changes +- Use @mentions for specific team member attention + +## Tagging guidelines + +Use the following labels to categorize tickets appropriately: + +- `a11y`: Accessibility-related issues and improvements +- `API`: Changes to component APIs or interfaces +- `docs`: Documentation updates or docs site changes +- `engineering-processes`: Engineering workflow and process improvements +- `feature`: New feature implementations +- `hold`: Tickets temporarily suspended or blocked +- `i18n`: Internationalization and localization work +- `iOS`: iOS-specific issues and bugs +- `mobile`: Mobile platform issues and responsive design +- `necromancy`: Backlog tickets older than 2 years requiring revival +- `product-processes`: Process improvements for product team collaboration +- `refactor`: Code restructuring and refactoring work +- `research`: Tasks requiring investigation or research +- `RFC`: Request for Comments documentation +- `s2foundations`: Spectrum 2 Foundations related work +- `spectrum2`: Spectrum 2 platform specific tasks +- `team-processes`: Internal team workflow improvements +- `testing`: Test implementation or testing infrastructure work +- `triage`: New tickets requiring team assessment and prioritization +- `VoiceOver`: VoiceOver screen reader specific issues + +Note: Labels should be applied at ticket creation and updated as needed throughout the ticket lifecycle. + +## Issue type + +Jira includes the following issue types: + +- Bug: For something in the code that needs to be fixed. +- Epic: For tickets that are larger than 8 story points and need to be broken up into multiple issues. +- Story: For tickets that tie to code deliverables. Whether that's research, an RFC, or a pull request, it counts! If you don't know what your issue type should be, this is a safe bet. +- Task: For work that doesn't relate to a code deliverable. diff --git a/.cursor/rules/styles.mdc b/.cursor/rules/styles.mdc new file mode 100644 index 0000000000..9f4b7a475d --- /dev/null +++ b/.cursor/rules/styles.mdc @@ -0,0 +1,14 @@ +--- +description: Rules for consistent styling in component CSS +globs: *.css +alwaysApply: true +--- + +1. Follow rules outlined in the `../../STYLING.md` file. +2. Auto-fix results based on settings defined by the `../../stylelint.config.js` unless it requires rewriting more than 30% of the line. Changes that impact more than 30% of the original content should prompt for update. +3. Copyrights should reflect the current year. +4. Comments added should always use sentence, never title case. +5. Any files removed should also be removed from the exports of the component's package.json. +6. Never rename a custom property without prompting for approval first or being expressly asked to update the custom property name. +7. Sort high-contrast and other media queries to the bottom of the CSS file. +8. Warn about or suggest fixes for duplicate properties; always opt to keep the definition that honors the CSS cascade. diff --git a/.cursor/rules/text-formatting.mdc b/.cursor/rules/text-formatting.mdc new file mode 100644 index 0000000000..5e588c51d9 --- /dev/null +++ b/.cursor/rules/text-formatting.mdc @@ -0,0 +1,46 @@ +--- +description: Text formatting and capitalization rules for documentation and tickets +globs: **/*.md, **/*.txt,**/*.mdx +alwaysApply: true +--- + +# Text formatting conventions + +## Capitalization rules + +- Use sentence case for all headings and section titles (capitalize first word only) + - Correct: "Getting started with components" + - Incorrect: "Getting Started With Components" +- Exceptions: Proper nouns, acronyms, and technical terms should maintain their standard capitalization (e.g., JavaScript, CSS, HTML, GitHub) +- Never use all caps except for: + - Established acronyms (e.g., API, HTML, CSS) + - Severity levels (e.g., SEV1, SEV2) + +## Markdown formatting + +- Use backticks (`) for: + - Code snippets + - File names + - Component names + - Technical terms +- Use bold (**) for: + - Section headers in structured content + - Important terms on first use + - UI element names +- Use italics (*) sparingly, only for: + - Term definitions + - Emphasis in technical explanations + +## Lists and bullets + +- Start each bullet point with a capital letter +- End each bullet point consistently (either all with periods or all without) +- Use parallel structure in lists (all items should be same grammatical form) + +## Technical writing style + +- Use present tense +- Use active voice +- Be concise and direct +- Avoid jargon unless technically necessary +- Define abbreviations on first use