Common issues caught in PR review

[jattasNI]

🧹 Tech Debt

We'll use this issue to collect common issues found in PR review. Put the issues in comments, feel free to edit other people's comments with more info (does everyone have that permission?)

Once we've collected enough we can figure out what to do with the list. Maybe a code review checklist, maybe training material, maybe automated lint rules to catch this stuff for us, maybe capturing it in CONTRIBUTING in more detail.

[jattasNI]

Beachball change files

1. wrong change type
2. description is vague or focuses on implementation rather than client impact
3. use the GitHub obfuscated email
4. bump of monorepo package that is a devDep should use "dependentChangeType": "none" to prevent unnecessary new release of packages using it

[jattasNI]

Testing

1. Page objects should not expose Element types as they leak implementation detail and expose too much API surface area. Instead they should expose methods that access specific properties of the element and return primitive types.
2. All functionality should be covered by auto tests
3. Tests should be at the appropriate level (unit test or Chromatic test)
4. If something's not covered by auto tests, the PR description should include justification

[jattasNI]

Storybook

1. Everything in the public API that we expect clients to use should be documented, including important events and methods. Documentation should follow the patterns of similar APIs on other components.
2. No new accessibility violations were introduced

[jattasNI]

Styles

1. Styles should be ordered according to our CSS conventions
2. Don't set size attributes to inherit
   See examples in discussion 1 and discussion 2
3. For sizing, use appropriate size tokens for the right context (i.e. control height), but for sizes without a context aligned token, use a size from the 4px grid size ramp.
   • Do not hard code specific pixel values, use the size ramp
   • If you need to add additional values to the size ramp, see the latest naming guidance decision
   • Yes the naming system for the fixed pixel size ramp is not great and uses the term "padding". It should still be used.
4. For configurable sizing, have the control respond to sizing based on normal CSS property configuration (i.e. control responds to setting height, width, etc) or expose a shadow part that can be sized.
   • Do not create new CSS custom properties to configure size, i.e. user has to set --ni-nimble-my-custom-component-height
   • Do not create custom attributes to control size, i.e. <nimble-my-control size="small"></nimble-my-control>
   • See following comment for more detail: Configurable / Additional heights for nimble controls #610 (comment)
5. The unset and revert keywords probably don't do what you think they do. Read the mdn docs carefully; they are probably not part of the solution you are looking for.
6. Be aware of the display modes being applied to a elements in a template. Largely we should be using one of the layouts flex/grid (block) or inline-flex/inline-grid (inline). If there are a lot of different display modes being used to layout a template that may be a sign to double check the layout at a high-level.

[jattasNI]

Component index.ts

1. Don't write logic in TypeScript if it can be expressed in the template or style instead. e.g. no size or style calculations in TS. No DOM manipulation in TS.

[jattasNI]

PR structure

1. PRs should do one thing and should not be too large
2. PR title and description should be clear and detailed

[mollykreis]

TypeScript

1. Disabling lint rules should be rare and have good justification
2. Use of non-null assertions (i.e. !) should be specific to places where TypeScript could not infer the type correctly. It should not be used to avoid properly handling corner cases in the code.

[rajsite]

Buddy Reviews

The Nimble Code Review process states that contributions from outside the Nimble dev team should have reviews from a member of the Nimble Team before moving to Owners review.

If you are outside the NI organization, create an issue for discussion ideally before creating a PR.

If you are inside the NI organization and new to contributing to Nimble reach out on the Design System Teams channel to discuss your goals and get a Nimble point of contact.

Current Nimble Contacts:

• Wafer Map Component @atmgrifter00
• NIC 2 @mollykreis
• LIMS Rich Text / Comments @m-akinc

[rajsite]

Component Templates

1. Don't use nullish coalescing in bindings in templates (other kinds of conditional logic should behave well).
   However, don't use any conditional logic in aggregate bindings (i.e. like when class is stitched together with multiple bindings).
   See detailed examples: Evaluate volatile template bindings #1843 (comment)