snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

.claude/rules/api-changelog.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "zerver/openapi/**"
+  - "api_docs/**"
+---
+
+# Documenting API Changes
+
+API changes must be documented fully using our double-entry changelog
+system. When starting an API change, reread `docs/documentation/api.md`
+to review the process for documenting an API change. Run
+`tools/create-api-changelog`; it generates an empty
+`api_docs/unmerged.d/ZF-XXXXXX.md` file (where `XXXXXX` is a random
+hex string the tool picks for you) and stages it for you. Document
+the changes in that file as an unordered list (`*` bullets) of the
+additions or changes, formatted to match `api_docs/changelog.md`.
+Don't add a `**Feature level**` heading; the merge tooling emits that
+itself.
+
+In the OpenAPI yaml (`zerver/openapi/zulip.yaml`), reference the same
+filename stem in **Changes** notes, e.g.,
+`**Changes**: New in Zulip 13.0 (feature level ZF-XXXXXX).` The merge
+process matches the `Zulip <version> (feature level ZF-XXXXXX)` shape
+and overwrites both the version and the placeholder with the real
+release version and final feature level. Use the upcoming release's
+version — the next major release after the latest one shipped (e.g.,
+13.0 while 12.0 is the current release), which you can read from the
+first `## Changes in Zulip X.Y` heading in `api_docs/changelog.md`.
+You must keep the literal `New in Zulip X.Y` format, or the merge
+tooling won't recognize the note and CI (`check-feature-level-updated`)
+will fail with the `ZF-` placeholder still in the file. Never update
+`API_FEATURE_LEVEL` manually.

.claude/rules/css.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "web/styles/**"
+---
+
+# Writing CSS
+
+- Use `em` units instead of `px` for computed CSS values that need to
+  scale with font size. Pixel approximations break at different zoom
+  levels and font-size settings.
+- **Review CSS for redundant rules.** After writing CSS, review the
+  full set of rules affecting the same elements. Look for rules that
+  are immediately overridden by a more specific selector, duplicated
+  selector lists, or cases where scoping (e.g., `:not()`) would
+  eliminate the need for an override.
+- **Check CSS change scope.** When modifying CSS, always check what
+  other pages or components use the same selectors, files, and
+  classes. Use `git grep` on class names and check webpack bundle
+  entries to understand which pages load the file. Prefer scoped
+  overrides (e.g., `.parent .target`) over modifying shared rules,
+  to avoid unintended changes to other parts of the app.
+- Use class or ID selectors, not bare tag selectors or attribute
+  selectors. If no suitable class exists, add one.
+
+When removing a CSS dependency (e.g., Bootstrap), audit the full
+property list of every rule, not just visually obvious properties like
+colors and backgrounds. Subtle properties like `line-height`, `margin`,
+`padding`, `text-decoration`, `font-weight`, and `border` are easy to
+miss but cause visible regressions. Check inherited properties too —
+e.g., a `body` rule's `line-height` or `margin` affects all descendants.

.claude/rules/frontend.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "web/**/*.{js,cjs,mjs,ts,cts,mts}"
+  - "web/**/*.hbs"
+---
+
+# Frontend Code
+
+- JavaScript/TypeScript code must use `const` or `let`, never `var`.
+- Avoid lodash in favor of modern ECMAScript primitives where available,
+  keeping in mind our browserlist.
+- Don't use `onclick` attributes in HTML; use event delegation
+- Don't access DOM APIs (`document.documentElement.style`, `$()`
+  selectors for specific elements) without guarding for node test
+  environments, where the DOM is mocked minimally. Check that the
+  element exists before using it.
+- Use `util.the($el)` instead of `$el[0]!` when a jQuery object should
+  hold exactly one element.
+- Use class or ID selectors, not bare tag selectors or attribute
+  selectors. If no suitable class exists, add one.

.claude/rules/python.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python Code
+
+- Don't use `Any` type annotations without comments justifying it.
+- Don't use `cursor.execute()` with string formatting (SQL injection risk)
+- Don't use `.extra()` in Django without careful review and commenting
+- Don't create N+1 query patterns:
+
+  ```python
+  # BAD
+  for bar in bars:
+      foo = Foo.objects.get(id=bar.foo_id)
+
+  # GOOD
+  foos = {f.id: f for f in Foo.objects.filter(id__in=[b.foo_id for b in bars])}
+  ```

.claude/rules/testing.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "zerver/tests/**"
+  - "zerver/webhooks/**"
+  - "web/tests/**"
+---
+
+# Testing Philosophy
+
+- Write end-to-end tests when possible verifying what's important, not
+  internal APIs.
+- Tests must work offline. Use fixtures (in `zerver/tests/fixtures`) for
+  external service testing and `responses` for simpler things.
+- Use time_machine and similar libraries to mock time.
+- Read `zerver/tests/test_example.py` for patterns.
+- A good failing test before implementing is good practice so your
+  test and code can jointly verify each other.
+- Remember to always assert state is correctly updated, not just "success".
+- In tests, don't assert on `assertLogs` output with
+  `any(phrase in line for line in mock_log.output)`; pin the full line
+  against `mock_log.output`, or a substring to a specific `mock_log.output[i]`.
+
+A common failure mode is failing to have test coverage for error
+conditions that require coverage (note `tools/coveragerc` excludes
+asserts). Run `test-backend --coverage FooTest` and check the coverage
+data to confirm that the new lines you added are in fact run by the
+tests.
+
+## For webhooks
+
+```bash
+./tools/test-backend zerver/webhooks/<integration>
+```

.claude/rules/ui-testing.md

@@ -0,0 +1,67 @@
+---
+paths:
+  - "web/**"
+  - "templates/**"
+---
+
+# Manual Testing for UI Changes
+
+If a PR makes frontend changes, manually verify the affected UI. This
+catches issues that automated tests miss. **Treat this checklist as
+blocking, not advisory** — every applicable item must be verified
+before the change is ready.
+
+Most of these items can be completed by an agent. Start with
+analyzing the files, because it is cheaper than the `/visual-test`
+skill (`.claude/skills/visual-test/SKILL.md`). For things you aren't
+sure about, ensure either the user completes the relevant visual
+tests or you've run the visual test skill on them.
+
+## Visual appearance
+
+- Is the new UI consistent with similar elements (alignment, spacing,
+  fonts, colors, sizes)? Find the closest existing analogues and compare
+  carefully.
+- Is alignment correct, both vertically and horizontally? Measure
+  programmatically with `getBoundingClientRect()` when in doubt —
+  don't eyeball it.
+- Does every state look right and match similar UI: hover, active,
+  disabled, focused, selected, empty, overflowing?
+- Did the change accidentally affect other parts of the UI? Use
+  `git grep` to check if modified CSS is used elsewhere.
+- CSS changes are notorious for unintended consequences — check every
+  page and component that shares the selectors you modified, and
+  demonstrate with pixel-precise before/after comparisons that there
+  are none.
+- Check all of the above in both light and dark themes when the
+  change could plausibly affect colors, contrast, or theme-dependent
+  imagery. Pure geometry/typography changes (`font-size`,
+  `line-height`, `margin`, `padding`, `display`, `font-weight`,
+  etc.) don't need a separate dark-theme pass —
+  `web/styles/dark_theme.css` only overrides colors, so a single
+  theme suffices for theme-invariant changes.
+
+## Responsiveness and internationalization
+
+- Does the UI look good at different window sizes? Check wide desktop
+  (1920px), typical laptop (1280px), tablet, and narrow phone (480px).
+  Any widths between these values should also work.
+- Would the UI break if translated strings were 1.5x longer than
+  English? What if they were half as long? Both directions matter.
+  Think about right-to-left languages too.
+
+## Functionality
+
+- Are live updates working as expected?
+- Is keyboard navigation, including tabbing to interactive elements, working?
+- Do screen readers get sensible labels and roles for new elements?
+- If the feature affects the message view, try different narrows: topic,
+  channel, Combined feed, direct messages.
+- If the feature affects the compose box, test both channel messages and
+  direct messages, and both ways of resizing.
+- If the feature requires elevated permissions, test as both a user who
+  has permissions and one who does not.
+- Think about feature interactions: could banners overlap? What about
+  resolved/unresolved topics? Collapsed or muted messages?
+- Think about edge cases in data: empty lists, very long names, single
+  items vs. hundreds, special characters in strings.