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