mirror of
https://github.com/nuxt/nuxt.git
synced 2024-11-27 08:02:01 +00:00
chore: update contribution guide (#4028)
* chore: update contribution guide * refactor: content-parity with doc contribution guide * fix: remove double double-dashes and add npm cmd
This commit is contained in:
parent
ea8c2a6505
commit
37fc2da568
106
CONTRIBUTING.md
106
CONTRIBUTING.md
@ -1,14 +1,72 @@
|
|||||||
# Contributing to Nuxt.js
|
# Contributing to Nuxt.js
|
||||||
|
|
||||||
|
First of all, thank you for considering to contribute to Nuxt.js! :heart:
|
||||||
|
|
||||||
|
## Reporting Issues
|
||||||
|
|
||||||
|
A great way to contribute to the project is to send a detailed report when you encounter an issue.
|
||||||
|
To make things easier for contributors and maintainers, we use [CMTY](https://cmty.app/nuxt/issues/new?repo=nuxt.js).
|
||||||
|
|
||||||
|
Please make sure to include a reproduction repository or [CodeSandBox](https://codesandbox.io/s/github/nuxt/codesandbox-nuxt/tree/master/)
|
||||||
|
so that bugs can be reproduced without great efforts. The better a bug can be reproduced, the faster we can start fixing it!
|
||||||
|
|
||||||
|
## Pull Requests
|
||||||
|
|
||||||
|
We'd love to see your pull requests, even if it's just to fix a typo!
|
||||||
|
|
||||||
|
However, any significant improvement should be associated to an existing
|
||||||
|
[feature request](https://cmty.app/nuxt/issues/feature-request?repo=nuxt.js)
|
||||||
|
or [bug report](https://cmty.app/nuxt/issues/bug-report?repo=nuxt.js).
|
||||||
|
|
||||||
|
### Getting started
|
||||||
|
|
||||||
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
|
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
|
||||||
2. Run `npm install` to install the dependencies.
|
2. Run `npm install` or `yarn install` to install the dependencies.
|
||||||
|
|
||||||
> _Note that both **npm** and **yarn** have been seen to miss installing dependencies. To remedy that, you can either delete the `node_modules` folder in your example app and install again or do a local install of the missing dependencies._
|
> _Note that both **npm** and **yarn** have been seen to miss installing dependencies. To remedy that, you can either delete the `node_modules` folder in your example app and install again or do a local install of the missing dependencies._
|
||||||
|
|
||||||
3. Add an example app to `examples/` before writing any code.
|
> If you are adding a dependency, please use `yarn add`. The `yarn.lock` file is the source of truth for all Nuxt dependencies.
|
||||||
4. Create a fixture app under `test/fixtures/`. See others for examples.
|
|
||||||
|
|
||||||
To run an example or fixture app with your copy of Nuxt, do:
|
### Test structure
|
||||||
|
|
||||||
|
A great PR, whether it includes a bug fix or a new feature, will often include tests.
|
||||||
|
To write great tests, let us explain our test structure:
|
||||||
|
|
||||||
|
#### Fixtures
|
||||||
|
|
||||||
|
The fixtures (found under `tests/fixtures`) contain several Nuxt applications. To keep build time as short as possible,
|
||||||
|
we don't build an own Nuxt application per test. Instead, the fixtures are built (`yarn test:fixtures`) before running
|
||||||
|
the actual unit tests.
|
||||||
|
|
||||||
|
Please make sure to **alter** or **add a new fixture** when submitting a PR to reflect the changes properly (if applicable).
|
||||||
|
|
||||||
|
Also, don't forget to **rebuild** a fixture after changing it by running the corresponding test
|
||||||
|
with `jest test/fixtures/my-fixture/my-fixture.test.js`!
|
||||||
|
|
||||||
|
#### Unit tests
|
||||||
|
|
||||||
|
The unit tests can be found in `tests/unit` and will be executed after building the fixtures. A fresh Nuxt server will be used
|
||||||
|
per test so that no shared state (except the initial state from the build step) is present.
|
||||||
|
|
||||||
|
After adding your unit tests, you can run them directly:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
jest test/unit/test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
Or you can run the whole unit test suite:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
yarn test:unit
|
||||||
|
```
|
||||||
|
|
||||||
|
Again, please be aware that you might have to rebuild your fixtures before!
|
||||||
|
|
||||||
|
### Testing your changes
|
||||||
|
|
||||||
|
While working on your PR you will likely want to check if your fixture is set up correctly or debug your current changes.
|
||||||
|
|
||||||
|
To do so you can use the Nuxt script itself to launch for example your fixture or an example app:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
bin/nuxt examples/your-app
|
bin/nuxt examples/your-app
|
||||||
@ -17,36 +75,32 @@ bin/nuxt test/fixtures/your-fixture-app
|
|||||||
|
|
||||||
> `npm link` could also (and does, to some extent) work for this, but it has been known to exhibit some issues. That is why we recommend calling `bin/nuxt` directly to run examples.
|
> `npm link` could also (and does, to some extent) work for this, but it has been known to exhibit some issues. That is why we recommend calling `bin/nuxt` directly to run examples.
|
||||||
|
|
||||||
Once you've modified Nuxt and seen your modifications reflected correctly in your example app and fixture, add `unit` and, if necessary, `e2e` tests that can ensure its functionality and future maintanability. Study other tests carefully for reference.
|
### Examples
|
||||||
|
|
||||||
## Running specific tests
|
If you are working on a larger feature, please set up an example app in `examples/`.
|
||||||
|
This will help greatly in understanding changes and also help Nuxt users to understand the feature you've built in-depth.
|
||||||
|
|
||||||
```sh
|
### Linting
|
||||||
npm install jest -g
|
|
||||||
jest test/unit/test.js
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running test suites
|
As you might have noticed already, we are using ESLint to enforce a code standard. Please run `yarn lint` before committing
|
||||||
|
your changes to verify that the code style is correct. If not, you can use `yarn lint --fix` or `npm run lint -- --fix` (no typo!) to fix most of the
|
||||||
|
style changes. If there are still errors left, you must correct them manually.
|
||||||
|
|
||||||
```sh
|
### Documentation
|
||||||
yarn test
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, per group:
|
If you are adding a new feature, do a refactoring or change the behavior of Nuxt in any other manner, you'll likely
|
||||||
|
want to document the changes. Please do so with a PR to the [docs](https://github.com/nuxt/docs/pulls) repository.
|
||||||
|
You don't have to write documentation up immediately (but please do so as soon as your pull request is mature enough).
|
||||||
|
|
||||||
```sh
|
### Final checklist
|
||||||
yarn test:fixtures
|
|
||||||
yarn test:unit
|
|
||||||
yarn test:e2e
|
|
||||||
```
|
|
||||||
|
|
||||||
## Debugging tests on macOS
|
When submitting your PR, there is a simple template that you have to fill out.
|
||||||
|
Please tick all appropriate "answers" in the checklists.
|
||||||
|
|
||||||
|
### Troubleshooting
|
||||||
|
|
||||||
|
#### Debugging tests on macOS
|
||||||
|
|
||||||
Searching for `getPort()` will reveal it's used to start new Nuxt processes during tests. It's been seen to stop working on macOS at times and may require you to manually set a port for testing.
|
Searching for `getPort()` will reveal it's used to start new Nuxt processes during tests. It's been seen to stop working on macOS at times and may require you to manually set a port for testing.
|
||||||
|
|
||||||
Another common issue is Nuxt processes that may hang in memory when running fixture tests. A ghost process will often prevent subsequent tests from working. Run `ps aux | grep -i node` to inspect any hanging test processes if you suspect this is happening.
|
Another common issue is Nuxt processes that may hang in memory when running fixture tests. A ghost process will often prevent subsequent tests from working. Run `ps aux | grep -i node` to inspect any hanging test processes if you suspect this is happening.
|
||||||
|
|
||||||
## Opening PRs
|
|
||||||
|
|
||||||
- Please make sure your PR passes the lint test (`npm run lint`).
|
|
||||||
- Please wait for tests to run and verify potential failures.
|
|
||||||
|
Loading…
Reference in New Issue
Block a user