1# Contributing 2 3���� Thanks for helping us improve this project! �� 4 5This document outlines some of the practices we care about. 6If you have any questions or suggestions about the process, 7feel free to [open an issue](#reporting-issues). 8 9## Code of Conduct 10 11The [Node.js Code of Conduct][] applies to this repo. 12 13[Node.js Code of Conduct]: https://github.com/nodejs/node/blob/master/CODE_OF_CONDUCT.md 14 15## Governance 16 17This project falls under the governance of the Node.js Diagnostics WG as 18described at <https://github.com/nodejs/diagnostics/blob/master/GOVERNANCE.md>. 19 20## Developer's Certificate of Origin 1.1 21 22By making a contribution to this project, I certify that: 23 24* (a) The contribution was created in whole or in part by me and I 25 have the right to submit it under the open source license 26 indicated in the file; or 27 28* (b) The contribution is based upon previous work that, to the best 29 of my knowledge, is covered under an appropriate open source 30 license and I have the right under that license to submit that 31 work with modifications, whether created in whole or in part 32 by me, under the same open source license (unless I am 33 permitted to submit under a different license), as indicated 34 in the file; or 35 36* (c) The contribution was provided directly to me by some other 37 person who certified (a), (b) or (c) and I have not modified 38 it. 39 40* (d) I understand and agree that this project and the contribution 41 are public and that a record of the contribution (including all 42 personal information I submit with it, including my sign-off) is 43 maintained indefinitely and may be redistributed consistent with 44 this project or the open source license(s) involved. 45 46## How Can I Contribute? 47 48### Reporting Issues 49 50If you find any mistakes in the docs or a bug in the code, 51please [open an issue in Github](https://github.com/nodejs/node-inspect/issues/new) so we can look into it. 52You can also [create a PR](#contributing-code) fixing it yourself of course. 53 54If you report a bug, please follow these guidelines: 55 56* Make sure the bug exists in the latest version. 57* Include instructions on how to reproduce the issue. 58 The instructions should be as minimal as possible 59 and answer the three big questions: 60 1. What are the exact steps you took? This includes the exact versions of node, npm, and any packages involved. 61 1. What result are you expecting? 62 1. What is the actual result? 63 64### Improving Documentation 65 66For small documentation changes, you can use [Github's editing feature](https://help.github.com/articles/editing-files-in-another-user-s-repository/). 67The only thing to keep in mind is to prefix the commit message with "docs: ". 68The default commit message generated by Github will lead to a failing CI build. 69 70For larger updates to the documentation 71it might be better to follow the [instructions for contributing code below](#contributing-code). 72 73### Contributing Code 74 75**Note:** If you're planning on making substantial changes, 76please [open an issue first to discuss your idea](#reporting-issues). 77Otherwise you might end up investing a lot of work 78only to discover that it conflicts with plans the maintainers might have. 79 80The general steps for creating a pull request are: 81 821. Create a branch for your change. 83 Always start your branch from the latest `master`. 84 We often prefix the branch name with our initials, e.g. `jk-a-change`. 851. Run `npm install` to install the dependencies. 861. If you're fixing a bug, be sure to write a test *first*. 87 That way you can validate that the test actually catches the bug and doesn't pass. 881. Make your changes to the code. 89 Remember to update the tests if you add new features or change behavior. 901. Run the tests via `npm test`. This will also run style checks and other validations. 91 You might see errors about uncommitted files. 92 This is expected until you commit your changes. 931. Once you're done, `git add .` and `git commit`. 94 Please follow the [commit message conventions](#commits--commit-messages) described below. 951. Push your branch to Github & create a PR. 96 97#### Code Style 98 99In addition to any linting rules the project might include, 100a few general rules of thumb: 101 102* Try to match the style of the rest of the code. 103* We prefer simple code that is easy to understand over terse, expressive code. 104* We try to structure projects by semantics instead of role. 105 E.g. we'd rather have a `tree.js` module that contains tree traversal-related helpers 106 than a `helpers.js` module. 107* Actually, if you create helpers you might want to put those into a separate package. 108 That way it's easier to reuse them. 109 110#### Commits & Commit Messages 111 112Please follow the [angular commit message conventions](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines). 113We use an automated tool for generating releases 114that depends on the conventions to determine the next version and the content of the changelog. 115Commit messages that don't follow the conventions will cause `npm test` (and thus CI) to fail. 116 117The short summary - a commit message should look like this: 118 119``` 120<type>: <subject> 121 122<body> 123 124<references> 125 126<footer> 127``` 128 129Everything but the first line is optional. 130The empty lines between the different parts are required. 131 132* `<type>`: One of the following: 133 - **feat:** Introduces a new feature. This will cause the minor version to go up. 134 - **fix:** A bug fix. Causes a patch version bump. 135 - **docs:** Changes to the documentation. 136 This will also cause an increase of the patch version so that the changes show up in the npm registry. 137 - **style:** Cleanup & lint rule fixes. 138 Note that often it's better to just amend the previous commit if it introduced lint errors. 139 - **refactor:** Changes to the code structure without fixing bugs or adding features. 140 - **perf:** Performance optimizations. 141 - **test:** Fixing existing tests or adding missing ones. 142 Just like with **style**, if you add tests to a feature you just introduced in the previous commit, 143 consider keeping the tests and the feature in the same commit instead. 144 - **chore:** Changes to the project setup and tools, dependency bumps, house-keeping. 145* `<subject>`: A [good git commit message subject](http://chris.beams.io/posts/git-commit/#limit-50). 146 - Keep it brief. If possible the whole first line should have at most 50 characters. 147 - Use imperative mood. "Create" instead of "creates" or "created". 148 - No period (".") at the end. 149* `<body>`: Motivation for the change and any context required for understanding the choices made. 150 Just like the subject, it should use imperative mood. 151* `<references>`: Any URLs relevant to the PR go here. 152 Use one line per URL and prefix it with the kind of relationship, e.g. "Closes: " or "See: ". 153 If you are referencing an issue in your commit body or PR description, 154 never use `#123` but the full URL to the issue or PR you are referencing. 155 That way the reference is easy to resolve from the git history without having to "guess" the correct link 156 even if the commit got cherry-picked or merged into a different project. 157* `<footer>`: This part only applies if your commit introduces a breaking change. 158 It's important this is present, otherwise the major version will not increase. 159 See below for an example. 160 161##### Examples 162 163A feature that introduces a breaking change: 164 165``` 166feat: Support --yes CLI option 167 168For existing projects all prompts can be inferred automatically. 169Manual confirmation for each default provides no value in that case. 170 171Closes https://github.com/my/project/issues/123 172 173BREAKING CHANGE: This removes support for interactive password entry. 174Users will have to login beforehand. 175``` 176 177A simple bug fix: 178 179``` 180fix: Handle multi-byte characters in search logic 181``` 182