Skip to content

Commit 1d70f34

Browse files
isekovanicisekovanic
authored
chore: add AGENTS.md file (#3237)
* chore: add AGENTS.md file * fix: test script * fix: remove accessibility as per agent remark * fix: more agent remarks
1 parent 503e9c8 commit 1d70f34

File tree

2 files changed

+192
-0
lines changed

2 files changed

+192
-0
lines changed

‎AGENTS.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Guidance for AI coding agents
2+
3+
File purpose: operational rules for automated or assisted code changes. Human-facing conceptual docs belong in `README.md` or the docs site.
4+
5+
## Repository purpose
6+
7+
Stream Chat SDKs for:
8+
9+
- React Native CLI
10+
- Expo
11+
12+
Goals: API stability, backward compatibility, predictable releases, strong test coverage, accessibility, and performance discipline.
13+
14+
## Tech & toolchain
15+
16+
- Languages: TypeScript, React (web + native)
17+
- Runtime: Node (use `nvm use` with `.nvmrc`)
18+
- Package manager: Yarn (V1)
19+
- Testing: Jest (unit)
20+
- Lint/Format: ESLint + Prettier
21+
- Build: Package-local build scripts (composed via root)
22+
- Release: Conventional Commits -> automated versioning/publishing
23+
- Platforms:
24+
- React Native: iOS and Android
25+
26+
## Environment setup
27+
28+
1. `nvm use`
29+
2. `yarn install`
30+
3. (Optional) Verify: `node -v` matches `.nvmrc`
31+
4. `cd package`
32+
5. `yarn install-all && cd ..`
33+
6. Run tests: `yarn test:unit`
34+
35+
## Project layout (high-level)
36+
37+
- `package/`
38+
- `native-package/` (`react-native` CLI specific bundle)
39+
- `expo-package/` (`Expo` specific bundle)
40+
- `.` (core UI SDK, shared between both bundles)
41+
- `examples/`
42+
- `ExpoMessaging/`
43+
- `SampleApp/`
44+
- `TypeScriptMessaging/`
45+
- Config roots: linting, tsconfig, playwright, babel
46+
- Do not edit generated output (`lib/`, build artifacts)
47+
48+
## Core commands (Runbook)
49+
50+
| Action | Command |
51+
|-------------------------|------------------------------|
52+
| Install deps | `yarn install` |
53+
| Full build | `yarn install-all` |
54+
| Watch (if available) | `yarn start` (add if absent) |
55+
| Lint | `yarn lint` |
56+
| Fix lint (if separate) | `yarn lint --fix` |
57+
| Unit tests (CI profile) | `yarn test:unit` |
58+
59+
## API design principles
60+
61+
- Semantic versioning
62+
- Use `@deprecated` JSDoc with replacement guidance
63+
- Provide migration docs for breaking changes
64+
- Avoid breaking changes; prefer additive evolution
65+
- Public surfaces: explicit TypeScript types/interfaces
66+
- Consistent naming: `camelCase` for functions/properties, `PascalCase` for components/types
67+
68+
### Deprecation lifecycle
69+
70+
1. Mark with `@deprecated` + rationale + alternative.
71+
2. Maintain for at least one minor release unless security-critical.
72+
3. Add to migration documentation.
73+
4. Remove only in next major.
74+
75+
## Performance guidelines
76+
77+
- Minimize re-renders (memoization, stable refs)
78+
- Use `React.memo` / `useCallback` / `useMemo` when profiling justifies
79+
- Clean up side effects (`AbortController` for network calls, unsubscribe listeners when unmounting)
80+
- Monitor bundle size; justify increases > 2% per package
81+
- Prefer lazy loading for optional heavy modules
82+
- Avoid unnecessary large dependency additions
83+
84+
## Error & logging policy
85+
86+
- Public API: throw descriptive errors or return typed error results (consistent with existing patterns)
87+
- No console noise in production builds
88+
- Internal debug logging gated behind env flag (if present)
89+
- Never leak credentials/user data in errors
90+
91+
## Concurrency & async
92+
93+
- Cancel stale async operations (media, network) when components unmount
94+
- Use `AbortController` for fetch-like APIs
95+
- Avoid race conditions: check instance IDs / timestamps before state updates
96+
97+
## Testing strategy
98+
99+
- Unit: pure functions, small components
100+
- React Native: target minimal smoke + platform logic (avoid flakiness)
101+
- Mocks/fakes: prefer shared test helpers
102+
- Coverage target: maintain or improve existing percentage (fail PR if global coverage drops)
103+
- File naming: `*.test.ts` / `*.spec.ts(x)`
104+
- Add tests for: new public API, bug fixes (regression test), performance-sensitive utilities
105+
106+
## CI expectations
107+
108+
- Mandatory: build, lint, type check, unit/integration tests, (optionally) E2E smoke
109+
- Node versions: those listed in matrix (see workflow YAML files under `.github/workflows/`)
110+
- Failing or flaky tests: fix or quarantine with justification PR comment (temporary)
111+
- Zero new warnings
112+
113+
## Release workflow (high-level)
114+
115+
1. Conventional Commit messages on PR merge
116+
2. Release automation aggregates commits
117+
3. Version bump + changelog + tag
118+
4. Publish to registry
119+
5. Deprecations noted in CHANGELOG
120+
6. Ensure docs updated prior to publishing breaking changes
121+
122+
## Dependency policy
123+
124+
- Avoid adding large deps without justification (size, maintenance)
125+
- Prefer existing utility packages
126+
- Run `yarn audit` (or equivalent) if adding security-impacting deps
127+
- Keep upgrades separate from feature changes when possible
128+
129+
## Samples & docs
130+
131+
- New public feature: update at least one sample app
132+
- Breaking changes: provide migration snippet
133+
- Keep code snippets compilable
134+
- Use placeholder keys (`YOUR_STREAM_KEY`)
135+
136+
## React Native specifics
137+
138+
- Clear Metro cache if module resolution has issues: `yarn react-native start --reset-cache` (for RN CLI) or `yarn expo start --dev-client -c` (for `Expo`)
139+
- Test on iOS + Android for native module or platform-specific UI changes
140+
- Avoid unguarded web-only APIs in shared code
141+
- If the apps in `/examples` are failing to build or install, run:
142+
- `watchman watch-del-all && rm -rf ~/Library/Developer/Xcode/DerivedData/*`
143+
- `(cd ios && bundle exec pod install)` (for RN CLI based sample apps)
144+
- `npx expo prebuild` (if changes have been done in `app.json` of `ExpoMessaging`)
145+
- `rm -rf ios && rm -rf android` (if new native modules have been installed in `ExpoMessaging`)
146+
147+
## Linting & formatting
148+
149+
- Run `yarn lint` before commit
150+
- Narrowly scope `eslint-disable` with inline comments and rationale
151+
- No broad rule disabling
152+
153+
## Commit / PR conventions
154+
155+
- Small, focused PRs
156+
- Include tests for changes
157+
- Screenshot or video for UI changes (before/after)
158+
- Label breaking changes clearly in description
159+
- Document public API changes
160+
161+
## Security
162+
163+
- No credentials or real user data
164+
- Use placeholders in examples
165+
- Scripts must error on missing critical env vars
166+
- Avoid introducing unmaintained dependencies
167+
168+
## Prohibited edits
169+
170+
- Do not edit build artifacts
171+
- `package/lib`
172+
- `ios` and `android` directories in `ExpoMessaging`
173+
- `ios/build` and `android/build` in the other sample apps
174+
- `node_modules` everywhere
175+
- Do not bypass lint/type errors with force merges
176+
177+
## Quick agent checklist (per commit)
178+
179+
- Build succeeds
180+
- Lint clean
181+
- Type check clean
182+
- Tests (unit/integration) green
183+
- Coverage not reduced
184+
- Public API docs updated if changed
185+
- Samples updated if feature surfaced
186+
- No new warnings
187+
- No generated files modified
188+
189+
---
190+
191+
Refine this file iteratively for agent clarity; keep human-facing explanations in docs site / `README.md`.

‎package/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"README.md"
2323
],
2424
"scripts": {
25+
"install-all": "(yarn install --force && (cd native-package && yarn install --force) && (cd expo-package && yarn install --force))",
2526
"build": "rimraf lib && yarn run --silent build-translations && bob build && yarn run --silent copy-translations",
2627
"build-translations": "i18next",
2728
"copy-translations": "echo '\u001b[34mℹ\u001b[0m Copying translation files to \u001b[34mlib/typescript/i18n\u001b[0m' && cp -R -f ./src/i18n ./lib/typescript/i18n && echo '\u001b[32m✓\u001b[0m Done Copying Translations'",

0 commit comments

Comments
 (0)