docs(nx): update contributing guide with latest instructions (#1529)
This commit is contained in:
Brandon
Jason Jean
parent
c16ef6339f
commit
e88babaf78
2
.github/PULL_REQUEST_TEMPLATE.md
vendored
2
.github/PULL_REQUEST_TEMPLATE.md
vendored
@ -1,4 +1,4 @@
|
||||
_[Please make sure you have read the submission guidelines before posting an PR](https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-pr)_
|
||||
_[Please make sure you have read the submission guidelines before posting an PR](https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#submit-pr)_
|
||||
|
||||
> _Please make sure that your commit message follows our format._
|
||||
|
||||
|
||||
@ -4,19 +4,34 @@ We would love for you to contribute to Nx! Read this document to see how to do i
|
||||
|
||||
## Got a Question?
|
||||
|
||||
We are trying to keep GitHub issues for bug reports and feature requests. Stack Overflow is a much better place to ask general questions about how to use Nx.
|
||||
We are trying to keep GitHub issues for bug reports and feature requests. Using the `nrwl` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/nrwl) is a much better place to ask general questions about how to use Nx.
|
||||
|
||||
## Found an Issue?
|
||||
|
||||
If you find a bug in the source code or a mistake in the documentation, you can help us by [submitting an issue](https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#submit-issue) to [our GitHub Repository](https://github.com/nrwl/nx). Even better, you can [submit a Pull Request](https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#submit-pr) with a fix.
|
||||
|
||||
## Project Structure
|
||||
|
||||
Source code and documentation are included in the top-level folders listed below.
|
||||
|
||||
- `docs` - Markdown and configuration files for documentation including tutorials, guides for each supported platform, and API docs.
|
||||
- `e2e` - E2E tests for Nx packages and schematics.
|
||||
- `packages` - Source code for Nx packages such as Angular, React, Web, and others including schematics and builders.
|
||||
- `scripts` - Miscellaneous scripts for project tasks such as building documentation, testing, and code formatting.
|
||||
|
||||
## Building the Project
|
||||
|
||||
After cloning the project run: `yarn`.
|
||||
After cloning the project to your machine, to install the dependencies, run:
|
||||
|
||||
After that run `yarn build` to build the `nx`, and `schematics` packages.
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
|
||||
After that run `yarn linknpm`.
|
||||
To build the `nx`, and `schematics` packages, run:
|
||||
|
||||
```bash
|
||||
yarn build
|
||||
```
|
||||
|
||||
### Running Unit Tests
|
||||
|
||||
@ -26,23 +41,33 @@ To make sure your changes do not break any unit tests, run the following:
|
||||
yarn test
|
||||
```
|
||||
|
||||
You can also run `yarn test:schematics` and `yarn test:nx` to test the schematics and nx packages individually.
|
||||
|
||||
If you need to test only the **collection/ngrx.spec.ts** test [for example], you can use an optional `$1` argument as follows:
|
||||
To test the schematics only, run:
|
||||
|
||||
```bash
|
||||
yarn test:schematics schematics/src/collection/ngrx/ngrx
|
||||
yarn test:schematics
|
||||
```
|
||||
|
||||
To test the Nx packages only, run:
|
||||
|
||||
```bash
|
||||
yarn test:nx
|
||||
```
|
||||
|
||||
For example, if you need to only run the **ngrx/ngrx.spec.ts** test suite, provide a path to the specific spec file, run:
|
||||
|
||||
```bash
|
||||
yarn test:schematics angular/src/schematics/ngrx/ngrx
|
||||
```
|
||||
|
||||
### Running E2E Tests
|
||||
|
||||
To make sure you changes do not break any unit tests, run the following:
|
||||
To make sure your changes do not break any E2E tests, run:
|
||||
|
||||
```bash
|
||||
yarn e2e
|
||||
```
|
||||
|
||||
Running e2e tests can take some time, so it is often useful to run a single test. You can do it as follows:
|
||||
Running E2E tests can take some time, so it is often useful to run a single test. To run a single suite of tests, run:
|
||||
|
||||
```bash
|
||||
yarn e2e affected
|
||||
@ -59,9 +84,9 @@ To build Nx on Windows, you need to use WSL.
|
||||
|
||||
### <a name="submit-issue"></a> Submitting an Issue
|
||||
|
||||
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
|
||||
Before you submit an issue, please search the issue tracker. An issue for your problem may already exist and has been resolved, or the discussion might inform you of workarounds readily available.
|
||||
|
||||
We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. Having a reproducible scenario gives us wealth of important information without going back & forth to you with additional questions like:
|
||||
We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it. Having a reproducible scenario gives us wealth of important information without going back and forth with you requiring additional information, such as:
|
||||
|
||||
- version of Nx used
|
||||
- version of Angular CLI used
|
||||
@ -70,9 +95,9 @@ We want to fix all the issues as soon as possible, but before fixing a bug we ne
|
||||
- 3rd-party libraries and their versions
|
||||
- and most importantly - a use-case that fails
|
||||
|
||||
A minimal reproduce scenario using allows us to quickly confirm a bug (or point out coding problem) as well as confirm that we are fixing the right problem.
|
||||
A minimal reproduction allows us to quickly confirm a bug (or point out coding problem) as well as confirm that we are fixing the right problem.
|
||||
|
||||
We will be insisting on a minimal reproduce scenario in order to save maintainers time and ultimately be able to fix more bugs. Interestingly, from our experience users often find coding problems themselves while preparing a minimal repository. We understand that sometimes it might be hard to extract essentials bits of code from a larger code-base but we really need to isolate the problem before we can fix it.
|
||||
We will be insisting on a minimal reproduction in order to save maintainers time and ultimately be able to fix more bugs. Interestingly, from our experience, users often find coding problems themselves while preparing a minimal repository. We understand that sometimes it might be hard to extract essentials bits of code from a larger code-base but we really need to isolate the problem before we can fix it.
|
||||
|
||||
You can file new issues by filling out our [issue form](https://github.com/nrwl/nx/issues/new).
|
||||
|
||||
@ -83,11 +108,12 @@ Please follow the following guidelines:
|
||||
- Make sure unit tests pass
|
||||
- Make sure e2e tests pass
|
||||
- Make sure you run `yarn format`
|
||||
- For documentation, check for spelling and grammatical errors.
|
||||
- Update your commit message to follow the guidelines below
|
||||
|
||||
#### Commit Message Guidelines
|
||||
|
||||
Commit message should follow the following format:
|
||||
The commit message should follow the following format:
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
@ -116,9 +142,11 @@ The scope must be one of the following:
|
||||
- frontend - anything angular specific
|
||||
- nx - dependency management, basic workspace structure, etc
|
||||
|
||||
##### Subject
|
||||
##### Subject and Body
|
||||
|
||||
The subject must contain a description of the change.
|
||||
The subject must contain a description of the change, and the body of the message contains any additional details to provide more context about the change.
|
||||
|
||||
Including the issue number that the PR relates to also helps with tracking.
|
||||
|
||||
#### Example
|
||||
|
||||
@ -126,17 +154,17 @@ The subject must contain a description of the change.
|
||||
feat(schematics): add an option to generate lazy-loadable modules
|
||||
|
||||
`ng generate lib mylib --lazy` provisions the mylib project in tslint.json
|
||||
|
||||
Closes #157
|
||||
```
|
||||
|
||||
#### Commitizen
|
||||
|
||||
To simplify and automate the process of commiting with this format,
|
||||
To simplify and automate the process of committing with this format,
|
||||
**Nx is a [Commitizen](https://github.com/commitizen/cz-cli) friendly repository**, just do `git add` and execute `yarn commit`.
|
||||
|
||||
## Migrations
|
||||
|
||||
Nx allows users to automatically upgrade to the newest version of the package. If you are introducing a change that would require the users to upgrade their workspace, add a migration to `packages/schematics/migrations`.
|
||||
|
||||
Migrations are named in the following fashion: `YYYYMMDD-name.ts` (e.g., 20171129-change-schema.ts).
|
||||
|
||||
The `yarn nx-migrate` command will run all the migrations after the one encoded in .angular-cli.json.
|
||||
Migrations are named using version numbers in the following fashion: `update-major-minor-patch/update-major-minor-patch.ts`, for example, `update-8-1-0/update-8-1-0.ts`.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user