|
| 1 | +# Contributing to nuxt-fathom |
| 2 | + |
| 3 | +✨ Thanks for contributing to **nuxt-fathom**! ✨ |
| 4 | + |
| 5 | +As a contributor, here are the guidelines we would like you to follow: |
| 6 | +- [Code of conduct](#code-of-conduct) |
| 7 | +- [How can I contribute?](#how-can-i-contribute) |
| 8 | +- [Using the issue tracker](#using-the-issue-tracker) |
| 9 | +- [Submitting a Pull Request](#submitting-a-pull-request) |
| 10 | +- [Coding rules](#coding-rules) |
| 11 | +- [Working with the code](#working-with-the-code) |
| 12 | + |
| 13 | +We also recommend that you read [How to Contribute to Open Source](https://opensource.guide/how-to-contribute). |
| 14 | + |
| 15 | +## Code of conduct |
| 16 | + |
| 17 | +Help us keep **nuxt-fathom** open and inclusive. Please read and follow our [Code of conduct](CODE_OF_CONDUCT.md). |
| 18 | + |
| 19 | +## How can I contribute? |
| 20 | + |
| 21 | +### Improve documentation |
| 22 | + |
| 23 | +As a **nuxt-fathom** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, etc. Take a look at the [documentation issues that need help](https://github.com/lostdesign/nuxt-fathom/labels/documentation). |
| 24 | + |
| 25 | +Please follow the [Documentation guidelines](#documentation). |
| 26 | + |
| 27 | +### Give feedback on issues |
| 28 | + |
| 29 | +Some issues are created without information requested in the [Bug report guideline](#bug-report). |
| 30 | +Help make them easier to resolve by adding any relevant information. |
| 31 | + |
| 32 | +Participating in the discussion is a good opportunity to get involved and influence the future direction of **nuxt-fathom**. |
| 33 | + |
| 34 | +### Fix bugs and implement features |
| 35 | + |
| 36 | +Confirmed bugs and ready-to-implement features are marked with the [help wanted label](https://github.com/lostdesign/nuxt-fathom/labels/bug). |
| 37 | +Post a comment on an issue to indicate you would like to work on it. |
| 38 | + |
| 39 | +## Using the issue tracker |
| 40 | + |
| 41 | +The issue tracker is the channel for [bug reports](#bug-report), [features requests](#feature-request) and [submitting pull requests](#submitting-a-pull-request) only. |
| 42 | + |
| 43 | +Before opening an issue or a Pull Request, please use the [GitHub issue search](https://github.com/lostdesign/nuxt-fathom/issues) to make sure the bug or feature request hasn't been already reported or fixed. |
| 44 | + |
| 45 | +### Bug report |
| 46 | + |
| 47 | +A good bug report shouldn't leave others needing to chase you for more information. Please try to be as detailed as possible in your report. |
| 48 | + |
| 49 | +### Feature request |
| 50 | + |
| 51 | +Feature requests are welcome, but take a moment to find out whether your idea fits with the scope and aims of the project. |
| 52 | +It's up to you to make a strong case to convince the project's developers of the merits of this feature. |
| 53 | + |
| 54 | +## Submitting a Pull Request |
| 55 | + |
| 56 | +Good pull requests, whether patches, improvements, or new features, are a fantastic help. |
| 57 | +They should remain focused in scope and avoid containing unrelated commits. |
| 58 | + |
| 59 | +**Please ask first** before embarking on any significant pull requests (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's maintainers might not want to merge into the project. |
| 60 | + |
| 61 | +If you have never created a pull request before, welcome 🎉 😄. |
| 62 | +[Here is a great tutorial](https://opensource.guide/how-to-contribute/#opening-a-pull-request) on how to send one :) |
| 63 | + |
| 64 | +Here is a summary of the steps to follow: |
| 65 | + |
| 66 | +1. [Set up the workspace](#set-up-the-workspace) |
| 67 | +2. If you cloned a while ago, get the latest changes from upstream and update dependencies: |
| 68 | +```bash |
| 69 | +$ git checkout main |
| 70 | +$ git pull upstream main |
| 71 | +$ rm -rf node_modules |
| 72 | +$ npm install |
| 73 | +``` |
| 74 | +3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix: |
| 75 | +```bash |
| 76 | +$ git checkout -b <topic-branch-name> |
| 77 | +``` |
| 78 | +4. Make your code changes, following the [Coding rules](#coding-rules) |
| 79 | +5. Push your topic branch up to your fork: |
| 80 | +```bash |
| 81 | +$ git push origin <topic-branch-name> |
| 82 | +``` |
| 83 | +6. [Open a Pull Request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request) with a clear title and description. |
| 84 | + |
| 85 | +**Tips**: |
| 86 | +- For ambitious tasks, open a Pull Request as soon as possible with the `[WIP]` prefix in the title, in order to get feedback and help from the community. |
| 87 | +- [Allow nuxt-fathom maintainers to make changes to your Pull Request branch](https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork). |
| 88 | + This way, we can rebase it and make some minor changes if necessary. |
| 89 | + All changes we make will be done in new commit, and we'll ask for your approval before merging them. |
| 90 | + |
| 91 | +## Coding rules |
| 92 | + |
| 93 | +### Source code |
| 94 | + |
| 95 | +To ensure consistency and quality throughout the source code, all code modifications must have: |
| 96 | +- No linting errors |
| 97 | +- [Valid commit message(s)](#commit-message-guidelines) |
| 98 | +- Documentation for new features |
| 99 | +- Updated documentation for modified features |
| 100 | + |
| 101 | +### Documentation |
| 102 | + |
| 103 | +To ensure consistency and quality, all documentation modifications must: |
| 104 | +- Refer to brand in [bold](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) with proper capitalization, i.e. **GitHub**, **nuxt-fathom**, **npm** |
| 105 | +- Prefer [tables](https://help.github.com/articles/organizing-information-with-tables) over [lists](https://help.github.com/articles/basic-writing-and-formatting-syntax/#lists) when listing key values, i.e. List of options with their description |
| 106 | +- Use [links](https://help.github.com/articles/basic-writing-and-formatting-syntax/#links) when you are referring to: |
| 107 | + - a **nuxt-fathom** concept described somewhere else in the documentation, i.e. How to [contribute](CONTRIBUTING.md) |
| 108 | + - a third-party product/brand/service, i.e. Integrate with [GitHub](https://github.com) |
| 109 | + - an external concept or feature, i.e. Create a [GitHub release](https://help.github.com/articles/creating-releases) |
| 110 | + - a package or module, i.e. The [`@lostdesign/nuxt-fathom`](https://github.com/lostdesign/nuxt-fathom) module |
| 111 | +- Use the [single backtick `code` quoting](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) for: |
| 112 | + - commands inside sentences, i.e. the `nuxt-fathom` command |
| 113 | + - programming language keywords, i.e. `function`, `async`, `String` |
| 114 | + - packages or modules, i.e. The [`@lostdesign/nuxt-fathom`](https://github.com/lostdesign/nuxt-fathom) module |
| 115 | +- Use the [triple backtick `code` formatting](https://help.github.com/articles/creating-and-highlighting-code-blocks) for: |
| 116 | + - code examples |
| 117 | + - configuration examples |
| 118 | + - sequence of command lines |
| 119 | + |
| 120 | +### Commit message guidelines |
| 121 | + |
| 122 | +#### Atomic commits |
| 123 | + |
| 124 | +If possible, make [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit), which means: |
| 125 | +- a commit should contain exactly one self-contained functional change |
| 126 | +- a functional change should be contained in exactly one commit |
| 127 | +- a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...) |
| 128 | + |
| 129 | +A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change. |
| 130 | + |
| 131 | +#### Commit message format |
| 132 | + |
| 133 | +Each commit message consists of a **header**, a **body** and a **footer**. |
| 134 | +The header has a special format that includes a **type**, a **scope** and a **subject**: |
| 135 | + |
| 136 | +```commit |
| 137 | +<type>(<scope>): <subject> |
| 138 | +<BLANK LINE> |
| 139 | +<body> |
| 140 | +<BLANK LINE> |
| 141 | +<footer> |
| 142 | +``` |
| 143 | + |
| 144 | +The **header** is mandatory and the **scope** of the header is optional. |
| 145 | + |
| 146 | +The **footer** can contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages). |
| 147 | + |
| 148 | +#### Revert |
| 149 | + |
| 150 | +If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. |
| 151 | +In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted. |
| 152 | + |
| 153 | +#### Type |
| 154 | + |
| 155 | +The type must be one of the following: |
| 156 | + |
| 157 | +| Type | Description | |
| 158 | +|--------------|-------------------------------------------------------------------------------------------------------------| |
| 159 | +| **build** | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) | |
| 160 | +| **ci** | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) | |
| 161 | +| **docs** | Documentation only changes | |
| 162 | +| **feat** | A new feature | |
| 163 | +| **fix** | A bug fix | |
| 164 | +| **perf** | A code change that improves performance | |
| 165 | +| **refactor** | A code change that neither fixes a bug nor adds a feature | |
| 166 | +| **style** | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) | |
| 167 | +| **test** | Adding missing tests or correcting existing tests | |
| 168 | + |
| 169 | +#### Subject |
| 170 | + |
| 171 | +The subject contains succinct description of the change: |
| 172 | + |
| 173 | +- use the imperative, present tense: "change" not "changed" nor "changes" |
| 174 | +- don't capitalize first letter |
| 175 | +- no dot (.) at the end |
| 176 | + |
| 177 | +#### Body |
| 178 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 179 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 180 | + |
| 181 | +#### Footer |
| 182 | +The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**. |
| 183 | + |
| 184 | +**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. |
| 185 | +The rest of the commit message is then used for this. |
| 186 | + |
| 187 | +#### Examples |
| 188 | + |
| 189 | +```commit |
| 190 | +fix(pencil): stop graphite breaking when too much pressure applied |
| 191 | +``` |
| 192 | + |
| 193 | +```commit |
| 194 | +feat(pencil): add 'graphiteWidth' option |
| 195 | +
|
| 196 | +Fix #42 |
| 197 | +``` |
| 198 | + |
| 199 | +```commit |
| 200 | +perf(pencil): remove graphiteWidth option |
| 201 | +
|
| 202 | +BREAKING CHANGE: The graphiteWidth option has been removed. |
| 203 | +
|
| 204 | +The default graphite width of 10mm is always used for performance reasons. |
| 205 | +``` |
| 206 | + |
| 207 | +## Working with the code |
| 208 | + |
| 209 | +### Set up the workspace |
| 210 | + |
| 211 | +[Fork](https://guides.github.com/activities/forking/#fork) the project, [clone](https://guides.github.com/activities/forking/#clone) your fork, configure the remotes and install the dependencies: |
| 212 | + |
| 213 | +```bash |
| 214 | +# Clone your fork of the repo into the current directory |
| 215 | +$ git clone https://github.com/lostdesign/nuxt-fathom |
| 216 | +# Navigate to the newly cloned directory |
| 217 | +$ cd nuxt-fathom |
| 218 | +# Assign the original repo to a remote called "upstream" |
| 219 | +$ git remote add upstream https://github.com/lostdesign/nuxt-fathom |
| 220 | +# Install the dependencies |
| 221 | +$ npm install |
| 222 | +``` |
| 223 | + |
| 224 | +### Commits |
| 225 | + |
| 226 | +The [lostdesign/nuxt-fathom](https://github.com/lostdesign/nuxt-fathom) repository uses [Commitizen](https://github.com/commitizen/cz-cli) to help you create [valid commit messages](#commit-message-guidelines). |
| 227 | + |
| 228 | +After staging your changes with `git add`, run `npm run commit` to start the interactive commit message CLI. |
0 commit comments