|
| 1 | +# Contributing to the Elastic Node.js OpenTelemetry SDK distribution |
| 2 | + |
| 3 | +This distribution is open source and we love to receive contributions. |
| 4 | +There are many ways to contribute: submitting bug reports and feature requests, |
| 5 | +submitting pull requests for issues, improving documentation, interacting on |
| 6 | +our discussion forum, etc. |
| 7 | + |
| 8 | +You can get in touch with us through [Discuss](https://discuss.elastic.co/tags/c/apm/nodejs), |
| 9 | +feedback and ideas are always welcome. |
| 10 | + |
| 11 | + |
| 12 | +## Code contributions |
| 13 | + |
| 14 | +If you have a bugfix or new feature that you would like to contribute, please do the following: |
| 15 | +- Double check in open issues if there are any related issues or PRs. |
| 16 | +- Consider whether the changes can best be added to upstream https://github/open-telemetry repositories. (Please ask if unsure!) |
| 17 | +- Open an issue, ensure that you have properly described the use-case and possible solutions, link related issues/PRs if any. |
| 18 | +- Open a PR and link the issue created in previous step with your code changes. |
| 19 | + |
| 20 | +Doing so allows to: |
| 21 | +- share knowledge and document a bug/missing feature; |
| 22 | +- get feedback if someone is already working on it or is having a similar issue; and |
| 23 | +- benefit from the team experience by discussing it first. There are lots of implementation details that might not be |
| 24 | +obvious at first sight. |
| 25 | + |
| 26 | + |
| 27 | +## Linting |
| 28 | + |
| 29 | +Ensure your code contribution pass our linting (style and static checking): |
| 30 | + |
| 31 | +``` |
| 32 | +npm run lint |
| 33 | +``` |
| 34 | + |
| 35 | +Often style checking issues can be automatically resolve by running: |
| 36 | + |
| 37 | +``` |
| 38 | +npm run lint:fix |
| 39 | +``` |
| 40 | + |
| 41 | + |
| 42 | +## Testing |
| 43 | + |
| 44 | +tl;dr: |
| 45 | + |
| 46 | +```shell |
| 47 | +npm ci |
| 48 | +cd packages/opentelemetry-node |
| 49 | +npm run test-services:start # requires Docker |
| 50 | +npm test |
| 51 | +npm run test-services:stop |
| 52 | +``` |
| 53 | + |
| 54 | +See [TESTING.md](./TESTING.md) for full details. |
| 55 | + |
| 56 | + |
| 57 | +## Commit message guidelines |
| 58 | + |
| 59 | +This repo *loosely* encourages commit messages per [Conventional |
| 60 | +Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary). It is helpful |
| 61 | +if the *first* commit for a pull-request follows this format. Follow-up |
| 62 | +commits on a feature branch do not need to conform to this format. |
| 63 | + |
| 64 | +``` |
| 65 | +<type>(<optional scope>): <description> |
| 66 | +
|
| 67 | +[Optional body paragraphs.] |
| 68 | +
|
| 69 | +[Optional footers, e.g. "Fixes: #123" or "Co-authored-by: ...".] |
| 70 | +``` |
| 71 | + |
| 72 | +1. The first line should contain **a short description of the change.** |
| 73 | + |
| 74 | + It may optionally be prefixed with a *type*: |
| 75 | + * "fix:" when fixing a bug |
| 76 | + * "feat:" when adding a new feature |
| 77 | + * "docs:" when only updating documentation |
| 78 | + * "refactor:" when refactoring code without changing functional behavior |
| 79 | + * "test:" when only updating tests |
| 80 | + * "perf:" when improving performance without changing functional behavior |
| 81 | + * "chore:" when making some other task that does not change functional behavior |
| 82 | + |
| 83 | + The "optional scope" is commonly a package name, e.g.: `fix(opentelemetry-node): ...`. |
| 84 | + |
| 85 | + Append a `!` if the change is a breaking change, e.g.: `fix!: re-write config system`. |
| 86 | + |
| 87 | +2. The second line MUST be blank. |
| 88 | + |
| 89 | +3. Optionally provide body paragraphs that **explain the what and why of the change,** and not the how. |
| 90 | + Wrap all lines at 72 columns, within reason (URLs, quoted output). |
| 91 | + |
| 92 | + If your commit introduces a breaking change, it should clearly explain the |
| 93 | + reason for the change, which situations would trigger the breaking change, |
| 94 | + and what is the exact change. |
| 95 | + |
| 96 | +5. If fixing an open issue, add a footer block of the form `Fixes: #123` or |
| 97 | + `Closes: #123`. If the change is strongly related to another issue, PR, |
| 98 | + discussion, or some link, add a `Refs: ...` footer. |
| 99 | + |
| 100 | +Of these guidelines, the bolded parts are the most important: A succinct |
| 101 | +description and a body that answers "what" and "why" will best help future |
| 102 | +maintainers of the software. |
| 103 | + |
| 104 | +An example: |
| 105 | + |
| 106 | +``` |
| 107 | +feat: initial ESM support |
| 108 | +
|
| 109 | +This adds initial and ECMAScript Module (ESM) support, i.e. `import ...`, |
| 110 | +via the `--experimental-loader=elastic-apm-node/loader.mjs` node option. |
| 111 | +This instruments a subset of modules -- more will follow in subsequent changes. |
| 112 | +
|
| 113 | +Other changes: |
| 114 | +- Fixes a fastify instrumentation issue where the exported `fastify.errorCodes` |
| 115 | + was broken by instrumentation (both CJS and ESM). |
| 116 | +- Adds a `runTestFixtures` utility that should be useful for running out of |
| 117 | + process instrumentation/agent tests. |
| 118 | +
|
| 119 | +Closes: #1952 |
| 120 | +Refs: #2343 |
| 121 | +``` |
| 122 | + |
| 123 | + |
| 124 | +## CHANGELOG.md guidelines |
| 125 | + |
| 126 | +The audience for commit messages is maintainers of the software. |
| 127 | +The *audience for the changelog is users of the software*. |
| 128 | +Often this means that the changelog should *not* just repeat the commit message summary. |
| 129 | + |
| 130 | +If your changes will impact the user of this distro, then describe how in |
| 131 | +the changelog. It is okay to use more space than a single line, to show |
| 132 | +example code and output. However, if the description is getting *very* long, |
| 133 | +then likely updated documentation is worthwhile. |
| 134 | + |
0 commit comments