|
1 | 1 | # Contributing to Rollbar.js |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to Rollbar.js! We welcome contributions from the community. |
| 3 | +Thanks for helping Rollbar.js! Whether you are polishing docs, reporting a bug, adding a framework example, or enhancing SDK features, your contribution matters. This SDK ships in mission-critical environments, so we lean on automation: tests, linting, formatting. That keeps changes low-risk while keeping the process open and welcoming. Jump in wherever you feel inspired and ask questions early and often. |
4 | 4 |
|
5 | | -## Getting Started |
| 5 | +Rollbar.js is also AI-coding-agent ready: `AGENTS.md` documents Codex-specific guidelines and `CLAUDE.md` covers Claude’s conventions so automated assistants can operate safely alongside humans. Feel free to point AI tools at these docs when co-authoring patches. |
6 | 6 |
|
7 | | -### Prerequisites |
| 7 | +## Ways to contribute |
8 | 8 |
|
9 | | -- Node.js version 18 or higher |
10 | | -- npm |
| 9 | +- Improve docs, READMEs, or examples to make Rollbar easier to adopt |
| 10 | +- Reproduce and fix bugs across browsers, Node, or React Native |
| 11 | +- Add tests, new features, or quality-of-life improvements |
| 12 | +- Share integration snippets, tutorials, or demo apps |
11 | 13 |
|
12 | | -### Setup |
| 14 | +If you are unsure where to start, browse the GitHub issues page (<https://github.com/rollbar/rollbar.js/issues>) or open an issue/discussion, and maintainers can help scope a task that fits your interests. |
13 | 15 |
|
14 | | -1. Fork the repository on GitHub |
15 | | -2. Clone your fork locally: |
| 16 | +## Quick start |
| 17 | + |
| 18 | +**Prerequisites** |
| 19 | + |
| 20 | +- Node.js 18+ and npm 9+ |
| 21 | +- A GitHub fork or branch you can push to |
| 22 | + |
| 23 | +**Setup** |
| 24 | + |
| 25 | +1. Fork the repository and clone your fork: |
16 | 26 | ```bash |
17 | | - git clone https://github.com/your-username/rollbar.js.git |
| 27 | + git clone https://github.com/<your-username>/rollbar.js.git |
18 | 28 | cd rollbar.js |
19 | 29 | ``` |
20 | | -3. Install dependencies: |
| 30 | +2. Install dependencies: |
21 | 31 | ```bash |
22 | 32 | npm install |
23 | 33 | ``` |
24 | | -4. Build the project: |
| 34 | +3. (Optional) Verify the baseline: |
25 | 35 | ```bash |
26 | | - npm run build |
| 36 | + npm run build:dev |
| 37 | + npm test |
27 | 38 | ``` |
28 | 39 |
|
29 | | -## Development Workflow |
| 40 | +Keep branches focused on a single improvement. CI reruns the full suite on every push, so you can rely on it while iterating. |
30 | 41 |
|
31 | | -### Running Tests |
| 42 | +## Local development workflow |
32 | 43 |
|
33 | | -Run all tests: |
| 44 | +### Linting and autofixes |
34 | 45 |
|
35 | | -```bash |
36 | | -npm test |
37 | | -``` |
| 46 | +- `npm run lint` checks the entire repo with ESLint’s flat config. |
| 47 | +- `npm run lint:fix` runs ESLint with `--fix`. Run this before every commit so import ordering, unused variables, and other autofixable issues are taken care of automatically. |
38 | 48 |
|
39 | | -Run only browser tests: |
| 49 | +### Formatting |
40 | 50 |
|
41 | | -```bash |
42 | | -npm run test-browser |
43 | | -``` |
| 51 | +- `npm run format` applies Prettier to JavaScript, configs, Markdown, JSON, and YAML. Run it before committing; it is safe to run repeatedly. |
| 52 | +- `npm run format:check` is the read-only version CI uses. Use it locally when you want to double-check a patch without mutating files. |
44 | 53 |
|
45 | | -Run only server tests: |
| 54 | +### Tests |
46 | 55 |
|
47 | | -```bash |
48 | | -npm run test-server |
49 | | -``` |
| 56 | +- `npm test` runs both browser (`npm run test:wtr`) and server (`npm run test:server`) suites. |
| 57 | +- Scope runs as needed: |
| 58 | + - `npm run test:wtr -- --watch` for browser tests with live reload. |
| 59 | + - `npm run test:server test/server.my-feature.test.js` to focus on one file. |
| 60 | +- `npm run validate` executes ES5 compatibility and example snippets. Use it when touching bundling, transports, or documentation code. |
50 | 61 |
|
51 | | -### Code Style |
| 62 | +### Builds |
52 | 63 |
|
53 | | -- We use ESLint for code quality. Run `npm run lint` before submitting |
54 | | -- Code should follow the existing style patterns in the codebase |
55 | | -- Use 2 spaces for indentation |
56 | | -- Use single quotes for strings |
| 64 | +- `npm run build:dev` compiles bundles in development mode (faster debug cycle). |
| 65 | +- `npm run build` + `npm run postbuild` mirrors the release pipeline; only run this when you need to inspect distributables. |
57 | 66 |
|
58 | | -### Making Changes |
| 67 | +## Code style philosophy |
59 | 68 |
|
60 | | -1. Create a feature branch from `master`: |
| 69 | +- Prettier defines whitespace, quotes, and wrapping. Never hand-format files. |
| 70 | +- ESLint (with `unused-imports`, `no-console`, etc.) enforces correctness. Let the tools win; rerun `npm run lint:fix && npm run format` if your editor disagrees. |
| 71 | +- Prefer small, incremental commits that respect the SDK’s ES module architecture and multi-platform outputs. Automation keeps everyone aligned, so let the tools guide you instead of enforcing personal style. |
61 | 72 |
|
62 | | - ```bash |
63 | | - git checkout -b my-feature-name |
64 | | - ``` |
| 73 | +## Pull request checklist |
65 | 74 |
|
66 | | -2. Make your changes and ensure: |
67 | | - - All tests pass |
68 | | - - Code follows our style guidelines |
69 | | - - New features include appropriate tests |
70 | | - - Documentation is updated if needed |
71 | | - - Examples are updated if needed |
| 75 | +Before opening or updating a PR: |
72 | 76 |
|
73 | | -3. Commit your changes with a clear message: |
74 | | - ```bash |
75 | | - git commit -m "Add feature: description of what you added" |
76 | | - ``` |
77 | | - |
78 | | -## Submitting a Pull Request |
79 | | - |
80 | | -1. Push your changes to your fork: |
81 | | - |
82 | | - ```bash |
83 | | - git push origin my-feature-name |
84 | | - ``` |
| 77 | +- `npm run lint:fix` and `npm run format` |
| 78 | +- `npm test` (plus any focused suites you touched) |
| 79 | +- `npm run validate` when build outputs, transports, or examples change |
| 80 | +- Update docs (`README.md`, `docs/`, `examples/`) for user-facing behavior |
| 81 | +- Document risk, testing evidence, and follow-ups in the PR description |
| 82 | +- Reference related issues and describe the user benefit in plain language |
85 | 83 |
|
86 | | -2. Open a pull request on GitHub against the `master` branch |
| 84 | +CI re-runs lint (`--max-warnings 0`), `format:check`, tests, and ES5/example validation on every push, so if something slips through locally it will be caught automatically, and there is no need to stress. |
87 | 85 |
|
88 | | -3. In your pull request description: |
89 | | - - Clearly describe what changes you've made |
90 | | - - Reference any related issues |
91 | | - - Include testing steps if applicable |
| 86 | +## Troubleshooting linting & formatting |
92 | 87 |
|
93 | | -4. Wait for review and address any feedback |
| 88 | +- **ESLint cannot find a plugin**: run `npm install` to ensure devDependencies are installed; the flat config loads plugins via native `import`, so Node 18+ is required. |
| 89 | +- **`unused-imports` keeps flagging helper params**: delete the import or prefix intentional unused params with `_` (e.g., `_req`) and rerun `npm run lint:fix`. |
| 90 | +- **Prettier rewrites the entire file**: confirm you are using the repo’s pinned Prettier version (`npm run format` handles it) or format just the file you touched (`npm run format -- src/foo.js`). |
| 91 | +- **CI fails `format:check` but local format looks fine**: make sure your editor isn’t stripping trailing newlines or converting line endings; set `git config core.autocrlf false` (Unix) or `true` (Windows) and format again. |
| 92 | +- **`eslint` reports “Parsing error: Cannot find module”**: ensure every import has a `.js` extension because Rollbar.js is pure ESM, and missing extensions break the parser. |
94 | 93 |
|
95 | | -## Reporting Issues |
| 94 | +Still stuck? Open a draft PR, start a GitHub Discussion, or tag maintainers in an issue; we’re happy to help. |
96 | 95 |
|
97 | | -- Use GitHub Issues to report bugs |
98 | | -- Include as much detail as possible: |
99 | | - - Steps to reproduce |
100 | | - - Expected behavior |
101 | | - - Actual behavior |
102 | | - - Environment details (browser, Node.js version, etc.) |
| 96 | +## Continuous integration expectations |
103 | 97 |
|
104 | | -## Questions? |
| 98 | +GitHub Actions runs lint, `format:check`, browser/server tests, ES5 validation, and documentation snippet checks on every PR. Hooks are optional; CI is the enforcer so you can iterate locally without fear. Keep patches scoped, trust the automation, and explain what you validated in your PR body. |
105 | 99 |
|
106 | | -If you have questions, please: |
| 100 | +## Need help? |
107 | 101 |
|
108 | | -- Check existing issues and documentation |
109 | | -- Open a GitHub issue for clarification |
110 | | -- Email [email protected] for urgent matters |
| 102 | +- Start a GitHub Discussion or issue for questions and feature ideas. |
| 103 | +- For security-sensitive findings, follow `SECURITY.md`. |
| 104 | +- Unsure where to contribute? Browse open GitHub issues or start a discussion describing what excites you, and maintainers will help scope the work. |
111 | 105 |
|
112 | | -Thank you for contributing to Rollbar.js! |
| 106 | +Thanks again for partnering with us to improve Rollbar.js! |
0 commit comments