mirror of https://github.com/nuxt/nuxt.git
134 lines
6.3 KiB
Markdown
134 lines
6.3 KiB
Markdown
# Contribution
|
|
|
|
Nuxt is a community project - and so we love contributions of all kinds! ❤️
|
|
|
|
There is a range of different ways you might be able to contribute to the Nuxt ecosystem.
|
|
|
|
## Triage issues and help out in discussions
|
|
|
|
Check out [our issues board](https://github.com/nuxt/framework/issues) and [discussions](https://github.com/nuxt/framework/discussions). Helping other users, sharing workarounds, creating reproductions, or even poking into a bug a little bit and sharing your findings makes a huge difference.
|
|
|
|
## Fixing a bug or adding a feature
|
|
|
|
Before you fix a bug or add a feature, ensure **there's an issue that describes it**. Particularly for new features, this is an excellent opportunity for the project leads to giving feedback before starting work on it.
|
|
|
|
### Examples
|
|
|
|
While working on your PR, you will likely want to check if your changes are working correctly.
|
|
|
|
You can modify the example app in `playground/`, and run it with `yarn dev`. Please make sure not to commit it to your branch, but it could be helpful to add some example code to your PR description. This can help reviewers and other Nuxt users understand the feature you've built in-depth.
|
|
|
|
### Testing
|
|
|
|
Every new feature should have a corresponding unit test (if possible). The `test` folder in this repository is currently a work in progress, but do your best to create a new test following the example of what's already there.
|
|
|
|
Before creating a PR or marking it as ready-to-review, ensure that all tests pass by running `yarn test` locally.
|
|
|
|
### Linting
|
|
|
|
You might have noticed already that we use ESLint to enforce a coding 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` to fix most of the style changes. If there are still errors left, you must correct them manually.
|
|
|
|
### Documentation
|
|
|
|
If you are adding a new feature or refactoring or changing the behavior of Nuxt in any other manner, you'll likely want to document the changes. Please include any changes to the docs in the same PR. You don't have to write documentation up on the first commit (but please do so as soon as your pull request is mature enough). Make sure to make changes according to the [Documentation Guide](#documentation-guide)/
|
|
|
|
### Final checklist
|
|
|
|
When submitting your PR, there is a simple template that you have to fill out. Please tick all appropriate "answers" in the checklists.
|
|
|
|
<!-- ## Create a module
|
|
|
|
If you've built something with Nuxt that's cool, why not [extract it into a module](/modules/kit), so it can be shared with others? We have [many excellent modules already](https://modules.nuxtjs.org/), but there's always room for more.
|
|
|
|
If you need help while building it, feel free to [check in with us](/community/getting-help). -->
|
|
|
|
Mainly, make sure your PR title adheres to [Conventional Commits guidelines](https://www.conventionalcommits.org/en/v1.0.0/), and do link the related issue (feature request or bug report) in the issue description.
|
|
|
|
## Documentation Guide
|
|
|
|
Documentation is one of the essential parts of Nuxt. We aim to be an intuitive framework - and a big part of that is making sure that both the developer experience and the docs are perfect. 👌
|
|
|
|
If you spot an area where we can improve documentation or error messages, please do open a PR - even if it's just to fix a typo!
|
|
|
|
In this section, you will find:
|
|
|
|
::list{type=success}
|
|
|
|
- How to contribute and submit your changes.
|
|
- Tips to keep the documentation helpful and inclusive for everyone.
|
|
|
|
::
|
|
|
|
### Quick Edits
|
|
|
|
If you spot a typo or want to rephrase a sentence, you can click on the **Edit this page on GitHub** link located after the content of every page.
|
|
Make the change directly in the GitHub interface and open a Pull Request.
|
|
|
|
### Longer Edits
|
|
|
|
The documentation content is inside the `docs/` directory of the [nuxt/framework repository](https://github.com/nuxt/framework) and written in markdown.
|
|
|
|
To contribute, fork the repository and follow [these steps](#setup-documentation-website-in-local-environment) and start docs in development mode.
|
|
|
|
After making your changes:
|
|
|
|
- Lint the documentation with the `lint:docs` command.
|
|
- Open a Pull Request. Please make sure your PR title adheres to the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines.
|
|
|
|
### Linting docs
|
|
|
|
Documentation is linted using [MarkdownLint](https://github.com/DavidAnson/markdownlint/) and [case police](https://github.com/antfu/case-police) to to keep the documentation cohesive.
|
|
|
|
### Writing tips
|
|
|
|
- Avoid subjective words like _simply_, _just_, _obviously..._ when possible.
|
|
|
|
Keep in mind your readers can have different backgrounds and experiences. Therefore, these words don't convey meaning and can be harmful.
|
|
|
|
::alert{icon=❌}
|
|
**Avoid:** "Simply make sure the function returns a promise."
|
|
::
|
|
|
|
::alert{icon=✅}
|
|
**Prefer:** "Make sure the function returns a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)."
|
|
::
|
|
|
|
- Prefer [active voice](https://developers.google.com/tech-writing/one/active-voice).
|
|
|
|
::alert{icon=❌}
|
|
**Avoid:** "An error will be thrown by Nuxt."
|
|
::
|
|
|
|
::alert{icon=✅}
|
|
**Prefer:** "Nuxt will throw an error."
|
|
::
|
|
|
|
## Set up your local development environment
|
|
|
|
To contribute to Nuxt, you need to setup a local environment.
|
|
|
|
1. [Fork](https://help.github.com/articles/fork-a-repo/) the [nuxt/framework repository](https://github.com/nuxt/framework) to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
|
|
|
|
1. Ensure using the latest Node.js (16.x)
|
|
|
|
1. Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
|
|
|
|
1. Run `yarn install` to install the dependencies.
|
|
|
|
> If you are adding a dependency, please use `yarn add`. The `yarn.lock` file is the source of truth for all Nuxt dependencies.
|
|
|
|
1. Run `yarn stub` to activate the passive development system
|
|
|
|
1. Check out a branch where you can work and commit your changes:
|
|
|
|
```bash
|
|
git checkout -b my-new-branch
|
|
```
|
|
|
|
### Setup documentation website in local environment
|
|
|
|
1. Follow steps to setup [local development environment](#set-up-your-local-development-environment)
|
|
1. Change to the `docs/` directory using `cd docs/`
|
|
1. Install docs dependencies using `yarn install`
|
|
1. Start docs in development mode using `yarn dev`
|