docs: community starter docs (#270)

This commit is contained in:
Daniel Roe 2021-06-25 10:36:38 +01:00 committed by GitHub
parent debe5a98b0
commit 5b8c4caecc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 116 additions and 0 deletions

View File

@ -1 +1,29 @@
# Getting Help
At some point you may find that there's an issue you need some help with. But don't worry! We're a friendly community of developers and we'd love to help.
## "I can't figure out how to __."
You've read through these docs and you think it should be possible, but it's not clear how. The best thing is to [open a GitHub Discussion](https://github.com/nuxt/framework/discussions).
Please don't feel embarrassed about asking a question that you think is easy - we've all been there! ❤️
Everyone you'll encounter is helping out because they care, not because they are paid to do so. The kindest thing to do is make it easy for them to help you. Here are some ideas:
* _Explain what your objective is, not just the problem you're facing._ "I need to ensure my form inputs are accessible, so I'm trying to get the ids to match between server and client."
* _Make sure you've first read the docs and used your favorite search engine_. Let people know by saying something like "I've Googled for 'nuxt script setup' but I couldn't find code examples anywhere."
* _Explain what you've tried._ Tell people the kind of solutions you've experimented with, and why. Often this can make people's advice more relevant to your situation.
* _Share your code._ People probably won't be able to help if they just see an error message or a screenshot - but that all changes if you share your code in a copy/pasteable format - preferably in the form of a minimal reproduction like a CodeSandbox.
And finally, just ask the question! There's no need to [ask permission to ask a question](https://dontasktoask.com/) or [wait for someone to reply to your 'hello'](https://www.nohello.com/). If you do, you might not get a response because people are waiting for the whole question before engaging.
## "Could there be a bug?"
Something isn't working the way that the docs say that it should. You're not sure if it's a bug. You've searched through the open issues and discussions but you can't find anything.
In that case, the best thing to do is to try to reproduce the bug in a minimal way, apart from the rest of your project. This is a great way to solve problems. There's [a Nuxt3 starter sandbox](https://codesandbox.io/s/github/nuxt/starter/tree/v3) you can fire up in the browser for exactly this purpose.
Even if you can't create a minimal reproduction, [please do report the bug](/community/reporting-bugs). Nuxt3 is still in active development, and every issue helps make it better.

View File

@ -1 +1,25 @@
# Reporting Bugs
Try as we might, we never completely eliminate bugs. One of the most valuable roles in open source is taking the time to report bugs helpfully. Even if you can't fix the underlying code, reporting a bug well can enable someone else with a bit more familiarity with the code base to spot a pattern or make a quick fix.
Here are a few key steps.
## Is it really a bug?
Consider if you're looking to get help with something, or whether you think there's a bug with Nuxt itself. If it's the former, we'd love to help you - but the best way to do that is through [asking for help](/community/getting-help) rather than reporting a bug.
## Search the issues
Search through the [open issues](https://github.com/nuxt/framework/issues) and [discussions](https://github.com/nuxt/framework/discussions) first. If you find anything that seems like the same bug, it's much better to comment on an existing thread than create a duplicate.
## Create a minimal reproduction
It's important to be able to reproduce the bug reliably - in a minimal way and apart from the rest of your project. This narrows down what could be causing the issue and makes it possible for someone not only to find the cause, but also to test a potential solution.
Start with [this Nuxt3 sandbox](https://codesandbox.io/s/github/nuxt/starter/tree/v3) and add the **minimum** amount of code necessary to reproduce the bug you're experiencing.
Once you've reproduced the issue, remove as much code from your reproduction as you can (while still recreating the bug). Time spent making the reproduction as minimal as possible will make a huge difference to whoever sets out to fix the issue.
## Figure out what the cause might be
With a Nuxt project, there are lots of moving pieces - from [community modules](https://modules.nuxtjs.org/) to [other JavaScript libraries](https://www.npmjs.com/). Try to report the bug at the most relevant and specific place. That will likely be the Nuxt module causing an issue, or the upstream library that Nuxt is depending on.

View File

@ -1 +1,65 @@
# Contribution
Nuxt is a community project - and so we love contributions of all kinds! ❤️
There are a range of different ways you might be able to contribute to the Nuxt ecosystem.
## 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 awesome 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).
## Improve our documentation
Documentation is one of the most important 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!
## 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 just poking into a bug a little bit and sharing your findings - it all 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 a great opportunity for the project leads to give feedback before starting work on it.
### Setup your dev environment
1. [Fork](https://help.github.com/articles/fork-a-repo/) the [Nuxt3 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.
2. Run `yarn` 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.
3. Check out a branch where you can work and commit your changes:
```
git checkout -b my-new-branch
```
### Examples
While working on your PR you will likely want to check if your changes are working correctly.
To do so you can modify the example app in `playground/`, and run it with `yarn play`. 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, make sure that all tests are passing by running `yarn test` locally.
### Linting
As you might have noticed already, we use 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` 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).
### 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.
Particularly, 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.