docs: consolidate clang-format docs.
Move the section from `CONTRIBUTING.md` (which should only be policy) to `DEVELOPER.md` (which should document developer tooling). Consolidates the whole thing a bit, and adjusts for the now always installed `git clang-format` hook. Also mentions clang-format's lookup behaviour.
This commit is contained in:
Martin Probst
parent
393f703a97
commit
d1f7900eeb
|
|
@ -28,8 +28,8 @@ If you find a bug in the source code or a mistake in the documentation, you can
|
|||
## <a name="feature"></a> Want a Feature?
|
||||
You can *request* a new feature by [submitting an issue](#submit-issue) to our [GitHub
|
||||
Repository][github]. If you would like to *implement* a new feature, please submit an issue with
|
||||
a proposal for your work first, to be sure that we can use it. Angular 2 is in developer preview
|
||||
and we are not ready to accept major contributions ahead of the full release.
|
||||
a proposal for your work first, to be sure that we can use it. Angular 2 is in developer preview
|
||||
and we are not ready to accept major contributions ahead of the full release.
|
||||
Please consider what kind of change it is:
|
||||
|
||||
* For a **Major Feature**, first open an issue and outline your proposal so that it can be
|
||||
|
|
@ -135,22 +135,9 @@ To ensure consistency throughout the source code, keep these rules in mind as yo
|
|||
|
||||
* All features or bug fixes **must be tested** by one or more specs (unit-tests).
|
||||
* All public API methods **must be documented**. (Details TBC).
|
||||
* With the exceptions listed below, we follow the rules contained in
|
||||
[Google's JavaScript Style Guide][js-style-guide]:
|
||||
* Wrap all code at **100 characters**.
|
||||
|
||||
### <a name="clang-format">clang-format</a>
|
||||
The Angular project uses [`clang-format`](http://clang.llvm.org/docs/ClangFormat.html) to
|
||||
automatically format its source and enforce the common coding style. A couple of tips:
|
||||
|
||||
* Install clang-format with `npm install -g clang-format`.
|
||||
* Use `clang-format -i [file name]` to format a file (or multiple).
|
||||
* Use `gulp enforce-format` to check if your code is `clang-format` clean. This also gives
|
||||
you a command line to format your code.
|
||||
* `clang-format` also includes a git hook, run `git clang-format` to format all files you
|
||||
touched.
|
||||
* `clang-format` integrations are available for many popular editors (`vim`, `emacs`,
|
||||
`Sublime Text`, etc.)
|
||||
* We follow [Google's JavaScript Style Guide][js-style-guide], but wrap all code at
|
||||
**100 characters**. An automated formatter is available, see
|
||||
[DEVELOPER.md](DEVELOPER.md#clang-format).
|
||||
|
||||
## <a name="commit"></a> Commit Message Guidelines
|
||||
|
||||
|
|
@ -188,7 +175,7 @@ Must be one of the following:
|
|||
generation
|
||||
|
||||
### Scope
|
||||
The scope could be anything specifying place of the commit change. For example
|
||||
The scope could be anything specifying place of the commit change. For example
|
||||
`Compiler`, `ElementInjector`, etc.
|
||||
|
||||
### Subject
|
||||
|
|
|
|||
44
DEVELOPER.md
44
DEVELOPER.md
|
|
@ -175,7 +175,7 @@ Karma is run against the new output.
|
|||
much easier to debug. `xit` and `xdescribe` can also be useful to exclude a test and a group of
|
||||
tests respectively.
|
||||
|
||||
### E2e tests
|
||||
### E2E tests
|
||||
|
||||
1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder).
|
||||
2. `$(npm bin)/gulp serve.js.prod serve.js.dart2js` (runs a local webserver).
|
||||
|
|
@ -195,30 +195,36 @@ Angular specific command line options when running protractor:
|
|||
Angular specific command line options when running protractor (e.g. force gc, ...):
|
||||
`$(npm bin)/protractor protractor-{js|dart2js}-conf.js --ng-help`
|
||||
|
||||
## Formatting
|
||||
## Formatting with <a name="clang-format">clang-format</a>
|
||||
|
||||
We use [clang-format](http://clang.llvm.org/docs/ClangFormat.html) to automatically enforce code style for our TypeScript code.
|
||||
This allows us to focus our code reviews more on the content, and less on style nit-picking.
|
||||
It also lets us encode our style guide in the `.clang-format` file in the repository,
|
||||
allowing many tools and editors to share our settings.
|
||||
We use [clang-format](http://clang.llvm.org/docs/ClangFormat.html) to automatically enforce code
|
||||
style for our TypeScript code. This allows us to focus our code reviews more on the content, and
|
||||
less on style nit-picking. It also lets us encode our style guide in the `.clang-format` file in the
|
||||
repository, allowing many tools and editors to share our settings.
|
||||
|
||||
To check the formatting of your code, run
|
||||
|
||||
gulp check-format
|
||||
|
||||
Note that the continuous build on Travis runs `gulp enforce-format`.
|
||||
Unlike the `check-format` task, this will actually fail the build if files aren't formatted according to the style guide.
|
||||
Note that the continuous build on Travis runs `gulp enforce-format`. Unlike the `check-format` task,
|
||||
this will actually fail the build if files aren't formatted according to the style guide.
|
||||
|
||||
Your life will be easier if you include the formatter in your standard workflow.
|
||||
Otherwise, you'll likely forget to check the formatting,
|
||||
and waste time waiting for a build on Travis that fails due to some whitespace difference.
|
||||
Your life will be easier if you include the formatter in your standard workflow. Otherwise, you'll
|
||||
likely forget to check the formatting, and waste time waiting for a build on Travis that fails due
|
||||
to some whitespace difference.
|
||||
|
||||
* **git pre-commit hook** is available at
|
||||
[llvm.org](https://llvm.org/svn/llvm-project/cfe/trunk/tools/clang-format/git-clang-format).
|
||||
This will automatically format your delta regions when you commit a change.
|
||||
To install, first patch this file to add `.ts` to the `default_extensions` section.
|
||||
Then copy the file somewhere in your path, for example, `/usr/local/git/current/bin/git-clang-format`.
|
||||
Make sure it is executable. Then, in the angular repo, run
|
||||
* Install clang-format with `npm install -g clang-format`.
|
||||
* Use `clang-format -i [file name]` to format a file (or multiple).
|
||||
Note that `clang-format` tries to load a `clang-format` node module close to the sources being
|
||||
formatted, or from the `$CWD`, and only then uses the globally installed one - so the version used
|
||||
should automatically match the one required by the project.
|
||||
Use `clang-format -version` in case you get confused.
|
||||
* Use `gulp enforce-format` to check if your code is `clang-format` clean. This also gives
|
||||
you a command line to format your code.
|
||||
* `clang-format` also includes a git hook, run `git clang-format` to format all files you
|
||||
touched.
|
||||
* You can run this as a **git pre-commit hook** to automatically format your delta regions when you
|
||||
commit a change. In the angular repo, run
|
||||
|
||||
```
|
||||
$ echo -e '#!/bin/sh\nexec git clang-format' > .git/hooks/pre-commit
|
||||
|
|
@ -237,7 +243,9 @@ Make sure it is executable. Then, in the angular repo, run
|
|||
- Program: [path to clang-format, try `$ echo $(npm config get prefix)/bin/clang-format`]
|
||||
- Parameters: `-i -style=file $FilePath$`
|
||||
- Working directory: `$ProjectFileDir$`
|
||||
|
||||
* `clang-format` integrations are also available for many popular editors (`vim`, `emacs`,
|
||||
`Sublime Text`, etc.).
|
||||
|
||||
## Project Information
|
||||
|
||||
### Folder structure
|
||||
|
|
|
|||
Loading…
Reference in New Issue