Skip to content

Commit 02cc100

Browse files
aweiss-devaweiss-dev
authored
chore(docs): add docs and copilot instructions (#19781)
* chore(docs): add docs and copilot instructions * chore: fix links * chore: make jira description action fail
1 parent a777140 commit 02cc100

File tree

9 files changed

+339
-17
lines changed

9 files changed

+339
-17
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 24 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,29 @@
1-
## Description
1+
# Pull Request
22

3-
<!-- Uncomment this section if your PR has UI changes -->
4-
<!--
5-
## Screenshots/Screencast (for UI changes)
6-
-->
3+
## Summary
74

8-
## Checklist
5+
- What did I change and why?
6+
- Risks and how to roll out / roll back (e.g. feature flags):
97

10-
- [ ] mentions the JIRA issue in the PR name (Ex. [WPB-XXXX])
11-
- [ ] PR has been self reviewed by the author;
12-
- [ ] Hard-to-understand areas of the code have been commented;
13-
- [ ] If it is a core feature, unit tests have been added;
8+
---
149

15-
<!-- Uncomment this section if it is necessary to understand the PR -->
16-
<!-- ## Important Details for the Reviewers
10+
## Security Checklist (required)
1711

18-
- use (x) data
19-
- can be reviewed commit-by-commit
20-
- be sure to look at ... -->
12+
- [ ] **External inputs are validated & sanitized** on client and/or server where applicable.
13+
- [ ] **API responses are validated**; unexpected shapes are handled safely (fallbacks or errors).
14+
- [ ] **No unsafe HTML is rendered**; if unavoidable, sanitization is applied **and** documented where it happens.
15+
- [ ] **Injection risks (XSS/SQL/command) are prevented** via safe APIs and/or escaping.
16+
17+
## Standards Acknowledgement (required)
18+
19+
- [ ] I have read and this PR **upholds** our [Coding Standards](https://github.com/wireapp/wire-webapp/tree/docs/coding-standards.md) and [Tech Radar Choices](https://github.com/wireapp/wire-webapp/tree/docs/tech-radar.md).
20+
21+
---
22+
23+
## Screenshots or demo (if the user interface changed)
24+
25+
## Notes for reviewers
26+
27+
- Trade-offs:
28+
- Follow-ups (linked issues):
29+
- Linked PRs (e.g. web-packages):

‎.github/copilot-instructions.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Copilot — Repository Instructions (Security-first)
2+
3+
## Goals & tone
4+
5+
- Apply our **Web Coding Standards** during **PR description drafting** and **code review**.
6+
- Prefer **specific, actionable** comments with short code examples.
7+
- Use severities: **[Blocker]**, **[Important]**, **[Suggestion]**.
8+
- Do **not** nitpick items handled by automation (formatting, lint rules).
9+
10+
Related docs:
11+
12+
- **Coding Standards:** https://github.com/wireapp/wire-webapp/tree/docs/coding-standards.md
13+
- **Tech Radar:** https://github.com/wireapp/wire-webapp/tree/docs/tech-radar.md
14+
15+
---
16+
17+
## PR description — Auto-checks Copilot should perform
18+
19+
---
20+
21+
## Security Checklist (required)
22+
23+
- [ ] **External inputs validated & sanitised** (client/server as applicable). _Tick if_ validation/sanitisation is visible before use.
24+
- [ ] **API responses validated**; unexpected shapes handled (fallbacks/errors). _Tick if_ guards/schemas are present at boundaries.
25+
- [ ] **No unsafe HTML is rendered**; if unavoidable, sanitisation is applied **and** noted where it happens. _Fail signal:_ `dangerouslySetInnerHTML` without sanitiser (e.g., `DOMPurify.sanitize`).
26+
- [ ] **Injection risks (XSS/SQL/command) mitigated** via safe APIs/escaping. _Tick if_ sinks are avoided or safely wrapped.
27+
28+
---
29+
30+
## When reviewing pull requests (Copilot)
31+
32+
**Scope & approach**
33+
34+
- Review **from the code diff only**; do not assume runtime behavior.
35+
- Use severities: **[Blocker]**, **[Important]**, **[Suggestion]**.
36+
- Provide concise, actionable comments; include a minimal before/after snippet where useful.
37+
38+
### Security (focus of inline review)
39+
40+
- Avoid/flag `dangerouslySetInnerHTML`; if present, require sanitisation and name the sanitizer.
41+
- No raw DOM insertion into trusted contexts; validate URLs/redirect targets.
42+
- Validate untrusted inputs and API responses **before** use; prefer schemas/guards.
43+
- Check for secrets/tokens in code, configs, and tests.
44+
- Call out missing error/fallback paths on boundary failures.
45+
46+
### Accessibility (minimum check)
47+
48+
- Keyboard access (Esc closes dialogs), visible focus, correct roles/labels.
49+
- Use of `aria-live` for async status where appropriate.
50+
51+
### Everything else
52+
53+
- For imports/TS/React/testing/naming/readability: **refer to** the [Coding Standards](https://github.com/wireapp/wire-webapp/tree/docs/coding-standards.md).
54+
- If a standard is violated, link the relevant section and suggest a minimal change.
55+
56+
### Technology choices
57+
58+
- Compare any new dependencies in `package.json`/lockfiles to the [Tech Radar](https://github.com/wireapp/wire-webapp/tree/docs/tech-radar.md).
59+
- If not **Adopt**/**Trial**, mark **[Blocker]** and request an RFC/approval link.
60+
- For **Trial**, ensure usage is narrowly scoped and success criteria exist.
61+
62+
---
63+
64+
## Comment format Copilot should use
65+
66+
**Top-level summary**
67+
68+
- Verdict: **Ready** / **Changes requested**, with counts of Blockers/Important/Suggestions.
69+
- Mini checklist (only items evidenced by diff): Security, Accessibility, Tech choices, (then link to Coding Standards for any non-security notes).
70+
71+
**Inline comments**
72+
73+
- One issue per comment with severity, file:line, brief reason, and (when helpful) a minimal suggested patch.
74+
75+
**Approval**
76+
77+
- Approve only if there are **no Blockers** and Important items are fixed or explicitly deferred with rationale.

‎.github/instructions/accessibility.instructions.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
appliesTo:
3+
paths:
4+
- 'src/**/*'
5+
---
6+
7+
# Copilot — Accessibility
8+
9+
- Ensure keyboard access is coded: focusable controls; Escape key closes dialogs; trap & restore focus in dialogs.
10+
- Use semantic elements; provide names/labels; add `aria-live` for async status updates where relevant.

‎.github/instructions/react.instructions.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
appliesTo:
3+
paths:
4+
- 'src/**/*.tsx'
5+
---
6+
7+
# Copilot — React code review rules
8+
9+
- Prefer event handlers or a data tool over `useEffect`.
10+
- If an effect is necessary, it must: (1) do one thing, (2) have stable deps, (3) avoid inline objects/functions in deps.
11+
- No derived state from props unless justified.
12+
- Keys in lists: stable unique ids; never array indexes.
13+
- Keep UI components “dumb”: render from props; move business logic to a separate module or hook.

‎.github/instructions/security.instructions.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
appliesTo:
3+
paths:
4+
- 'src/**/*'
5+
---
6+
7+
# Copilot — Security hygiene
8+
9+
- Validate and sanitise **all untrusted input** and **all API responses**.
10+
- Avoid `dangerouslySetInnerHTML`. If used, it must be sanitised and commented with the sanitizer reference.
11+
- Avoid raw DOM insertion and unvalidated URLs; suggest safe helpers.

‎.github/instructions/typescript.instructions.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
appliesTo:
3+
paths:
4+
- 'src/**/*.ts'
5+
- 'src/**/*.tsx'
6+
---
7+
8+
# Copilot — TypeScript safety
9+
10+
- Do not use `any`, type casts (`as T`/`<T>`), or the non-null operator `!`.
11+
- Exported APIs must have explicit types. Narrow with type guards (or schemas) at boundaries.
12+
- Handle `null`/`undefined` explicitly; avoid `@ts-ignore` (unless narrowly scoped with a reason).

‎.github/workflows/jira-lint-and-link.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ jobs:
88
if: ${{ github.actor != 'dependabot[bot]' }}
99
runs-on: ubuntu-latest
1010
steps:
11-
- uses: cakeinpanic/jira-description-action@v0.9.0
11+
- uses: cakeinpanic/jira-description-action@master
1212
name: jira-description-action
1313
with:
1414
github-token: ${{ secrets.GITHUB_TOKEN }}
1515
jira-token: ${{ secrets.JIRA_TOKEN }}
1616
jira-base-url: https://wearezeta.atlassian.net
1717
skip-branches: '^(dev|master|release\/*)$'
18-
fail-when-jira-issue-not-found: false
18+
fail-when-jira-issue-not-found: true

‎docs/coding-standards.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Coding Standards
2+
3+
These standards guide everyday code contributions. They complement the Security Checklist in the PR template.
4+
5+
## 1) Imports, Exports, and Module Boundaries
6+
7+
- Use **named exports only**; avoid default exports.
8+
- Use **named imports only**; do not rename imports with `as`.
9+
- Avoid circular dependencies; keep module boundaries clear.
10+
11+
## 2) TypeScript: Type Safety & Validation
12+
13+
- Avoid `any`, type assertions/casts (`as`, `<Type>`) and the non-null `!` operator unless absolutely necessary and justified.
14+
- Prefer type guards for safe narrowing.
15+
- Validate external data (user input, API responses, storage) before use; handle unexpected shapes.
16+
17+
## 3) Naming, Documentation, and Readability
18+
19+
- Use descriptive names; avoid vague terms/abbreviations.
20+
- Add JSDoc-style comments for methods (purpose, parameters, returns).
21+
- Prefer one statement per line (including split chained calls).
22+
- Prefer modern TS/JS features (destructuring, spread/rest).
23+
24+
## 4) Coding Style & Functionality
25+
26+
- Minimize variable scope; declare variables near first use.
27+
- Prefer early returns over deep nesting.
28+
- Keep helper functions pure and side-effect free.
29+
- Prefer arrow functions unless `this/arguments` semantics are required.
30+
- Ensure no unhandled promises.
31+
32+
## 5) React: Effects, State, and Components
33+
34+
- Do **not** reach for `useEffect` by default; trigger actions from events.
35+
- Use declarative data tools instead of hand-wired effects where possible.
36+
- Each effect has a single responsibility with minimal, stable deps.
37+
- Avoid inline objects/functions that cause re-renders.
38+
- Keep components “dumb” and focused—render from props; move logic up.
39+
- Prefer functional components + hooks.
40+
- Use stable keys in lists (never array indexes).
41+
42+
## 6) Abstraction and Duplication
43+
44+
- Duplication is sometimes better than a wrong abstraction.
45+
- Inline first; abstract once patterns stabilize.
46+
- Be willing to delete/inline poor abstractions.
47+
48+
## 7) Accessibility (a11y)
49+
50+
- Full keyboard support; visible focus; Escape closes modals.
51+
- Use appropriate ARIA landmarks/roles; live regions for async updates.
52+
- Custom components follow accessible patterns (e.g., focus-trapped dialogs, proper labeling, sensible tab order).
53+
54+
## 8) Testing
55+
56+
- Component unit tests for new/changed logic (cover success & failure paths).
57+
- E2E tests for affected critical paths, or mark N/A with a reason.
58+
- For TS modules, include meaningful unit tests; emphasize public APIs; prefer pure functions.
59+
60+
## 9) Technology Choices ([Tech Radar](./tech-radar.md))
61+
62+
- Use well-understood, approved technologies.
63+
- If introducing experimental tech, keep usage limited, justify it.
64+
- Do not introduce unrecommended tech; prefer refactoring/migrating away.
65+
66+
## 10) Documentation
67+
68+
- Update documentation when behavior or usage changes.
69+
- Document migrations.
70+
- Keep PR title/description clear and consistent with the change.
71+
- Link the PR to the relevant Jira ticket.
72+
73+
## 11) PR Formatting & Media
74+
75+
- For UI/design changes, include screenshots or a short video.
76+
- For technical PRs, include a clear description of the problem, scope, and user impact.
77+
- Add inline comments on critical paths/logic to guide reviewers.
78+
79+
---
80+
81+
**Note:** Security-critical checks live in the PR template’s “Security Checklist” and must be explicitly acknowledged there.

‎docs/tech-radar.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Tech Radar
2+
3+
A living map of our technology choices, organized by areas and levels of adoption.
4+
5+
- **Last review:** 19.08.2025
6+
- **Reviewed by:** [Wire Web Team](https://github.com/orgs/wireapp/teams/web)
7+
- **Review frequency:** Once per year
8+
- **Next review:** 19.08.2026
9+
10+
## Levels
11+
12+
- **Adopt** - Proven and recommended; default for new work.
13+
- **Trial** - Limited, production-adjacent evaluation with success criteria.
14+
- **Assess** - Research/POCs only; not for critical paths yet.
15+
- **Hold** - Avoid for new work; plan migration away when feasible.
16+
17+
---
18+
19+
## 🧩 UI Libraries & Frameworks
20+
21+
| Technology | Adopt | Trial | Assess | Hold |
22+
| --------------------------------------- | :---: | :---: | :----: | :--: |
23+
| React | ✅ | | | |
24+
| zod | ✅ | | | |
25+
| lexical | ✅ | | | |
26+
| typescript | ✅ | | | |
27+
| electron | ✅ | | | |
28+
| tanstack/react-table | ✅ | | | |
29+
| tanstack/react-virtual | | ✅ | | |
30+
| axios | ✅ | | | |
31+
| tanstack-query _(team-management only)_ | ✅ | | | |
32+
| Axios Cache Interceptor | | ✅ | | |
33+
| react-router | ✅ | | | |
34+
| cmdk | | | ✅ | |
35+
36+
---
37+
38+
## 🎨 Styling
39+
40+
| Technology | Adopt | Trial | Assess | Hold |
41+
| ----------------------------------- | :---: | :---: | :----: | :--: |
42+
| LESS | | | | ✅ |
43+
| Emotion _(object styles, `styled`)_ | ✅ | | | |
44+
| radix-ui | | | | ✅ |
45+
| react-select | ✅ | | | |
46+
| react-transition-group | ✅ | | | |
47+
| tailwind | | | ✅ | |
48+
49+
---
50+
51+
## 📦 Build & Tooling
52+
53+
| Technology | Adopt | Trial | Assess | Hold |
54+
| ---------- | :---: | :---: | :----: | :--: |
55+
| webpack | ✅ | | | |
56+
| prettier | ✅ | | | |
57+
| eslint | ✅ | | | |
58+
| husky | ✅ | | | |
59+
| swc | ✅ | | | |
60+
| lerna-lite | | | | ✅ |
61+
| storybook | ✅ | | | |
62+
| vite | | | ✅ | |
63+
| nx | | | ✅ | |
64+
65+
---
66+
67+
## 🧠 State Management
68+
69+
| Technology | Adopt | Trial | Assess | Hold |
70+
| ------------------------------ | :---: | :---: | :----: | :--: |
71+
| zustand _(Factories)_ | ✅ | | | |
72+
| dexie.js | ✅ | | | |
73+
| redux | | | | ✅ |
74+
| tsyringe _(Singleton Classes)_ | ✅ | | | |
75+
| knockout.js observables | | | | ✅ |
76+
| amplify | | | | ✅ |
77+
78+
---
79+
80+
## 🧪 Testing
81+
82+
| Technology | Adopt | Trial | Assess | Hold |
83+
| --------------- | :---: | :---: | :----: | :--: |
84+
| Jest | ✅ | | | |
85+
| Playwright | ✅ | | | |
86+
| testing-library | ✅ | | | |
87+
| jasmine | | | | ✅ |
88+
89+
---
90+
91+
## Snapshot
92+
93+
> Quick scan of choices across all quadrants.
94+
95+
- **Adopt**: React; zod; lexical; typescript; electron; tanstack/react-table; axios; tanstack-query _(team-management only)_; react-router; Emotion; react-select; react-transition-group; webpack; prettier; eslint; husky; swc; storybook; zustand _(Factories)_; dexie.js; tsyringe _(Singleton Classes)_; Jest; Playwright; testing-library
96+
97+
- **Trial**: tanstack/react-virtual; Axios Cache Interceptor
98+
99+
- **Assess**: tailwind; vite; nx; cmdk
100+
101+
- **Hold**: LESS; radix-ui; lerna-lite; redux; knockout.js observables; amplify; jasmine
102+
103+
---
104+
105+
## Decision Log
106+
107+
| Date | Change | Ring | Quadrant | Notes |
108+
| ---------- | ------------------------------- | ---- | -------- | ------------------------------------ |
109+
| 18.11.2025 | Annual review snapshot captured | — | — | Imported from team radar screenshots |

0 commit comments

Comments
 (0)