honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 2015-06-22 09:45:53 -07:00
parent 393f703a97
commit d1f7900eeb
2 changed files with 32 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
CONTRIBUTING.md
View File

@ -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? ## <a name="feature"></a> Want a Feature?
You can *request* a new feature by [submitting an issue](#submit-issue) to our [GitHub 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 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 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. and we are not ready to accept major contributions ahead of the full release.
Please consider what kind of change it is: 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 * 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 features or bug fixes **must be tested** by one or more specs (unit-tests).
* All public API methods **must be documented**. (Details TBC). * All public API methods **must be documented**. (Details TBC).
* With the exceptions listed below, we follow the rules contained in * We follow [Google's JavaScript Style Guide][js-style-guide], but wrap all code at
[Google's JavaScript Style Guide][js-style-guide]: **100 characters**. An automated formatter is available, see
* Wrap all code at **100 characters**. [DEVELOPER.md](DEVELOPER.md#clang-format).
### <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.)
## <a name="commit"></a> Commit Message Guidelines ## <a name="commit"></a> Commit Message Guidelines
@ -188,7 +175,7 @@ Must be one of the following:
generation generation
### Scope ### 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. `Compiler`, `ElementInjector`, etc.
### Subject ### Subject

44
DEVELOPER.md
View File

@ -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 much easier to debug. `xit` and `xdescribe` can also be useful to exclude a test and a group of
tests respectively. tests respectively.
### E2e tests ### E2E tests
1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder). 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). 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, ...): Angular specific command line options when running protractor (e.g. force gc, ...):
`$(npm bin)/protractor protractor-{js|dart2js}-conf.js --ng-help` `$(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. We use [clang-format](http://clang.llvm.org/docs/ClangFormat.html) to automatically enforce code
This allows us to focus our code reviews more on the content, and less on style nit-picking. style for our TypeScript code. This allows us to focus our code reviews more on the content, and
It also lets us encode our style guide in the `.clang-format` file in the repository, less on style nit-picking. It also lets us encode our style guide in the `.clang-format` file in the
allowing many tools and editors to share our settings. repository, allowing many tools and editors to share our settings.
To check the formatting of your code, run To check the formatting of your code, run
gulp check-format gulp check-format
Note that the continuous build on Travis runs `gulp enforce-format`. Note that the continuous build on Travis runs `gulp enforce-format`. Unlike the `check-format` task,
Unlike the `check-format` task, this will actually fail the build if files aren't formatted according to the style guide. 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. Your life will be easier if you include the formatter in your standard workflow. Otherwise, you'll
Otherwise, you'll likely forget to check the formatting, likely forget to check the formatting, and waste time waiting for a build on Travis that fails due
and waste time waiting for a build on Travis that fails due to some whitespace difference. to some whitespace difference.
* **git pre-commit hook** is available at * Install clang-format with `npm install -g clang-format`.
[llvm.org](https://llvm.org/svn/llvm-project/cfe/trunk/tools/clang-format/git-clang-format). * Use `clang-format -i [file name]` to format a file (or multiple).
This will automatically format your delta regions when you commit a change. Note that `clang-format` tries to load a `clang-format` node module close to the sources being
To install, first patch this file to add `.ts` to the `default_extensions` section. formatted, or from the `$CWD`, and only then uses the globally installed one - so the version used
Then copy the file somewhere in your path, for example, `/usr/local/git/current/bin/git-clang-format`. should automatically match the one required by the project.
Make sure it is executable. Then, in the angular repo, run 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 $ 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`] - Program: [path to clang-format, try `$ echo $(npm config get prefix)/bin/clang-format`]
- Parameters: `-i -style=file $FilePath$` - Parameters: `-i -style=file $FilePath$`
- Working directory: `$ProjectFileDir$` - Working directory: `$ProjectFileDir$`
* `clang-format` integrations are also available for many popular editors (`vim`, `emacs`,
`Sublime Text`, etc.).
## Project Information ## Project Information
### Folder structure ### Folder structure