|
1 | 1 | # Maintainers Guide |
2 | 2 |
|
3 | | -This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain |
4 | | -this project. If you use this package within your own software as is but don't plan on modifying it, this guide is |
| 3 | +This document describes tools, tasks and workflow that one needs to be familiar |
| 4 | +with in order to effectively maintain this project. If you use this package |
| 5 | +within your own software as is but don't plan on modifying it, this guide is |
5 | 6 | **not** for you. |
6 | 7 |
|
7 | 8 | ## Tasks |
8 | 9 |
|
9 | 10 | ### Testing |
10 | 11 |
|
11 | | -Run unit tests locally using the `npm test` command. Tests are also run automatically on all branches using [Travis CI](https://travis-ci.org/slackhq/vscode-hack). |
| 12 | +Run unit tests locally using the `npm test` command. Tests are also run |
| 13 | +automatically on all branches using |
| 14 | +[Travis CI](https://travis-ci.org/slackhq/vscode-hack). |
12 | 15 |
|
13 | 16 | ### Releasing |
14 | 17 |
|
15 | | -This extension is published at https://marketplace.visualstudio.com/items?itemName=pranayagarwal.vscode-hack. |
| 18 | +This extension is published at |
| 19 | +https://marketplace.visualstudio.com/items?itemName=pranayagarwal.vscode-hack. |
16 | 20 |
|
17 | 21 | To push a new release, follow these steps: |
18 | 22 |
|
19 | | -1. Make sure the `master` branch is up to date with all changes and has been tested, and the Travis build is passing. |
| 23 | +1. Make sure the `master` branch is up to date with all changes and has been |
| 24 | + tested. |
20 | 25 | 2. Merge a new commit with the following changes: |
21 | | - - Update the version in `package.json` by following the versioning guide below |
| 26 | + - Update the version in `package.json` by following the versioning guide |
| 27 | + below |
22 | 28 | - Add a description of all changes since the last release in `CHANGELOG.md` |
23 | | - - Add or update the "Latest releases" section in `README.md` with release highlights |
| 29 | + - Add or update the "Latest releases" section in `README.md` with release |
| 30 | + highlights |
24 | 31 | 3. Draft a new GitHub release: |
25 | 32 | - Releases should always target the `master` branch |
26 | | - - Tag version and release title should both be in the format "v1.2.3", with the version matching the value in `package.json` |
| 33 | + - Tag version and release title should both be in the format "v1.2.3", with |
| 34 | + the version matching the value in `package.json` |
27 | 35 | - Copy your new section from `CHANGELOG.md` in the release description |
28 | | -4. Once the release is published, a new Travis build will automatically start. Ensure that the build passes and the following build tasks are successful: |
29 | | - - A new `vscode-hack-[version].vsix` is added as an asset to the GitHub release page |
30 | | - - The new version of the extension is publised on the Visual Studio Marketplace (this may take some time) |
| 36 | +4. Once the release is published, a new Travis build will automatically start. |
| 37 | + Ensure that the build passes and the following build tasks are successful: |
| 38 | + - A new `vscode-hack-[version].vsix` is added as an asset to the GitHub |
| 39 | + release page |
| 40 | + - The new version of the extension is publised on the Visual Studio |
| 41 | + Marketplace (this may take some time) |
31 | 42 |
|
32 | 43 | ## Workflow |
33 | 44 |
|
34 | 45 | ### Versioning and Tags |
35 | 46 |
|
36 | | -Even though this project is not published as an npm package, it uses a rough form of semver for versioning. Increment the MAJOR or MINOR version for feature additions, depending on size and impact, and PATCH version for bug fixes. |
| 47 | +Even though this project is not published as an npm package, it uses a rough |
| 48 | +form of semver for versioning. Increment the MAJOR or MINOR version for feature |
| 49 | +additions, depending on size and impact, and PATCH version for bug fixes. |
37 | 50 |
|
38 | | -Releases are tagged in git and published on the repository releases page on GitHub. |
| 51 | +Releases are tagged in git and published on the repository releases page on |
| 52 | +GitHub. |
39 | 53 |
|
40 | 54 | ### Branches |
41 | 55 |
|
42 | | -All development should happen in feature branches. `master` should be ready for quick patching and publishing at all times. |
| 56 | +All development should happen in feature branches. `master` should be ready for |
| 57 | +quick patching and publishing at all times. |
43 | 58 |
|
44 | 59 | ### Issue Management |
45 | 60 |
|
46 | | -Labels are used to run issues through an organized workflow. Here are the basic definitions: |
| 61 | +Labels are used to run issues through an organized workflow. Here are the basic |
| 62 | +definitions: |
47 | 63 |
|
48 | | -- `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been |
49 | | - documented and the issue has been reproduced. |
50 | | -- `enhancement` or `feature request`: A feature request for something this package might not already do. |
| 64 | +- `bug`: A confirmed bug report. A bug is considered confirmed when reproduction |
| 65 | + steps have been documented and the issue has been reproduced. |
| 66 | +- `enhancement` or `feature request`: A feature request for something this |
| 67 | + package might not already do. |
51 | 68 | - `docs`: An issue that is purely about documentation work. |
52 | 69 | - `tests`: An issue that is purely about testing work. |
53 | | -- `needs feedback`: An issue that may have claimed to be a bug but was not reproducible, or was otherwise missing some information. |
54 | | -- `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues. |
55 | | -- `question`: An issue that is like a support request because the user's usage was not correct. |
56 | | -- `semver:major|minor|patch`: Metadata about how resolving this issue would affect the version number. |
| 70 | +- `needs feedback`: An issue that may have claimed to be a bug but was not |
| 71 | + reproducible, or was otherwise missing some information. |
| 72 | +- `discussion`: An issue that is purely meant to hold a discussion. Typically |
| 73 | + the maintainers are looking for feedback in this issues. |
| 74 | +- `question`: An issue that is like a support request because the user's usage |
| 75 | + was not correct. |
| 76 | +- `semver:major|minor|patch`: Metadata about how resolving this issue would |
| 77 | + affect the version number. |
57 | 78 | - `security`: An issue that has special consideration for security reasons. |
58 | | -- `good first contribution`: An issue that has a well-defined relatively-small scope, with clear expectations. It helps when the testing approach is also known. |
59 | | -- `duplicate`: An issue that is functionally the same as another issue. Apply this only if you've linked the other issue by number. |
60 | | -- `external`: An issue that is caused by an external dependency and cannot be fixed here. |
61 | | - |
62 | | -**Triage** is the process of taking new issues that aren't yet "seen" and marking them with a basic |
63 | | -level of information with labels. An issue should have **one** of the following labels applied: |
64 | | -`bug`, `enhancement`, `question`, `needs feedback`, `docs`, `tests`, or `discussion`. |
65 | | - |
66 | | -Issues are closed when a resolution has been reached. If for any reason a closed issue seems |
67 | | -relevant once again, reopening is great and better than creating a duplicate issue. |
| 79 | +- `good first contribution`: An issue that has a well-defined relatively-small |
| 80 | + scope, with clear expectations. It helps when the testing approach is also |
| 81 | + known. |
| 82 | +- `duplicate`: An issue that is functionally the same as another issue. Apply |
| 83 | + this only if you've linked the other issue by number. |
| 84 | +- `external`: An issue that is caused by an external dependency and cannot be |
| 85 | + fixed here. |
| 86 | + |
| 87 | +**Triage** is the process of taking new issues that aren't yet "seen" and |
| 88 | +marking them with a basic level of information with labels. An issue should have |
| 89 | +**one** of the following labels applied: `bug`, `enhancement`, `question`, |
| 90 | +`needs feedback`, `docs`, `tests`, or `discussion`. |
| 91 | + |
| 92 | +Issues are closed when a resolution has been reached. If for any reason a closed |
| 93 | +issue seems relevant once again, reopening is great and better than creating a |
| 94 | +duplicate issue. |
68 | 95 |
|
69 | 96 | ## Everything else |
70 | 97 |
|
|
0 commit comments