|
| 1 | +--- |
| 2 | +type: docs |
| 3 | +title: "Contributing to the JavaScript SDK" |
| 4 | +linkTitle: "JavaScript SDK" |
| 5 | +weight: 3000 |
| 6 | +description: Guidelines for contributing to the Dapr JavaScript SDK |
| 7 | +--- |
| 8 | + |
| 9 | +When contributing to the [JavaScript SDK](https://github.com/dapr/js-sdk) the following rules and best-practices should be followed. |
| 10 | + |
| 11 | +💡 You can run `npm pretty-fix` to run prettier on all your files |
| 12 | + |
| 13 | +## Commit Guidelines |
| 14 | + |
| 15 | +The Dapr Javascript SDK uses the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) |
| 16 | +specification. The automatic changelog tool uses these to automatically generate |
| 17 | +a changelog based on the commit messages. Here's a guide to writing a commit message |
| 18 | +to allow this: |
| 19 | + |
| 20 | +### Format |
| 21 | + |
| 22 | +``` |
| 23 | +type(scope)!: subject |
| 24 | +``` |
| 25 | + |
| 26 | +- `type`: the type of the commit is one of the following: |
| 27 | + |
| 28 | + - `feat`: new features. |
| 29 | + - `fix`: bug fixes. |
| 30 | + - `docs`: documentation changes. |
| 31 | + - `refactor`: refactor of a particular code section without introducing |
| 32 | + new features or bug fixes. |
| 33 | + - `style`: code style improvements. |
| 34 | + - `perf`: performance improvements. |
| 35 | + - `test`: changes to the test suite. |
| 36 | + - `ci`: changes to the CI system. |
| 37 | + - `build`: changes to the build system (we don't yet have one so this shouldn't apply). |
| 38 | + - `chore`: for other changes that don't match previous types. This doesn't appear |
| 39 | + in the changelog. |
| 40 | + |
| 41 | +- `scope`: section of the codebase that the commit makes changes to. If it makes changes to |
| 42 | + many sections, or if no section in particular is modified, leave blank without the parentheses. |
| 43 | + Examples: |
| 44 | + |
| 45 | + - Commit that adds a `test`: |
| 46 | + |
| 47 | + ``` |
| 48 | + test(actors): add an actor test |
| 49 | + ``` |
| 50 | + |
| 51 | + - Commit that changes many things at once: |
| 52 | + |
| 53 | + ``` |
| 54 | + style: adopt eslint |
| 55 | + ``` |
| 56 | + |
| 57 | + For changes to examples, the scope should be the example name with the `examples/` prefix: |
| 58 | + |
| 59 | + - ❌ `fix(agnoster): commit subject` |
| 60 | + - ✅ `fix(examples/http/actor): commit subject` |
| 61 | + |
| 62 | +- `!`: this goes after the `scope` (or the `type` if scope is empty), to indicate that the commit |
| 63 | + introduces breaking changes. |
| 64 | + |
| 65 | + Optionally, you can specify a message that the changelog tool will display to the user to indicate |
| 66 | + what's changed and what they can do to deal with it. You can use multiple lines to type this message; |
| 67 | + the changelog parser will keep reading until the end of the commit message or until it finds an empty |
| 68 | + line. |
| 69 | + |
| 70 | + Example (made up): |
| 71 | + |
| 72 | + ``` |
| 73 | + style(agnoster)!: change dirty git repo glyph |
| 74 | +
|
| 75 | + BREAKING CHANGE: the glyph to indicate when a git repository is dirty has |
| 76 | + changed from a Powerline character to a standard UTF-8 emoji. |
| 77 | +
|
| 78 | + Fixes #420 |
| 79 | +
|
| 80 | + Co-authored-by: Username <email> |
| 81 | + ``` |
| 82 | + |
| 83 | +- `subject`: a brief description of the changes. This will be displayed in the changelog. If you need |
| 84 | + to specify other details you can use the commit body but it won't be visible. |
| 85 | + |
| 86 | + Formatting tricks: the commit subject may contain: |
| 87 | + |
| 88 | + - Links to related issues or PRs by writing `#issue`. This will be highlighted by the changelog tool: |
| 89 | + |
| 90 | + ``` |
| 91 | + feat(archlinux): add support for aura AUR helper (#9467) |
| 92 | + ``` |
| 93 | +
|
| 94 | + - Formatted inline code by using backticks: the text inbetween backticks will also be highlighted by |
| 95 | + the changelog tool: |
| 96 | + ``` |
| 97 | + feat(shell-proxy): enable unexported `DEFAULT_PROXY` setting (#9774) |
| 98 | + ``` |
| 99 | +
|
| 100 | +### Style |
| 101 | +
|
| 102 | +Try to keep the first commit line short. This is harder to do using this commit style but try to be |
| 103 | +concise and if you need more space, you can use the commit body. Try to make sure that the commit |
| 104 | +subject is clear and precise enough that users will know what change by just looking at the changelog. |
| 105 | +
|
| 106 | +## Github Dapr Bot Commands |
| 107 | +
|
| 108 | +Checkout the [daprbot documentation](https://docs.dapr.io/contributing/daprbot/) for Github commands you can run in this repo for common tasks. For example, you can run the `/assign` (as a comment on an issue) to assign issues to a user or group of users. |
| 109 | +
|
| 110 | +## Coding Rules |
| 111 | +
|
| 112 | +To ensure consistency throughout the source code, keep these rules in mind as you are working: |
| 113 | +
|
| 114 | +- All features or bug fixes **must be tested** by one or more specs (unit-tests). |
| 115 | +- All public API methods **must be documented**. |
| 116 | +- We follow [ESLint RecommendedRules](https://eslint.org/docs/rules/). |
| 117 | +
|
| 118 | +## Examples |
| 119 | +
|
| 120 | +The `examples` directory contains code samples for users to run to try out specific functionality of the various JavaScript SDK packages and extensions. When writing new and updated samples keep in mind: |
| 121 | +
|
| 122 | +- All examples should be runnable on Windows, Linux, and MacOS. While JavaScript code is consistent among operating systems, any pre/post example commands should provide options through [tabpane]({{% ref "contributing-docs.md#tabbed-content" %}}). |
| 123 | +- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine. |
| 124 | +
|
| 125 | +## Docs |
| 126 | +
|
| 127 | +The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind: |
| 128 | +
|
| 129 | +- All rules in the [docs guide]({{% ref contributing-docs.md %}}) should be followed in addition to these. |
| 130 | +- All files and directories should be prefixed with `js-` to ensure all file/directory names are globally unique across all Dapr documentation. |
0 commit comments