Skip to content

Commit 72b0bc5

Browse files
bajtosbajtos
committed
docs: add CONTRIBUTING, DEVELOPING and VSCODE
Add a short CONTRIBUTING.md file serving as a collection of links pointing to other documentation. Start a guide for developers in DEVELOPING.md. Describe VS Code setup in VSCODE.md, document steps needed to verify integration with tsc and tslint. Add docs/apidocs.html as an index file pointing to apidoc files of individual monorepo packages.
1 parent e5a9ce8 commit 72b0bc5

File tree

4 files changed

+359
-0
lines changed

4 files changed

+359
-0
lines changed

‎docs/CONTRIBUTING.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Contributing to LoopBack
2+
3+
Contributions to Node.js include code, documentation, answering user questions, and advocating for all types of Node.js users. See our official documentation on loopback.io for more information common to all of our GitHub repositories:
4+
5+
- http://loopback.io/doc/en/contrib/index.html
6+
7+
## [Principles](http://loopback.io/doc/en/contrib/Governance.html#principles)
8+
9+
LoopBack is an open, inclusive, and tolerant community of people working together to build a world-class Node framework and tools. We value diversity of individuals and opinions, and seek to operate on consensus whenever possible. We strive to maintain a welcoming, inclusive, and harassment-free environment, regardless of the form of communication. When consensus is not achievable, we defer to the owners of each individual module; the powers of the individual owner are kept in check by the ability of the community to fork and replace dependencies on the individual module and maintainer.
10+
11+
## [Reporting issues](http://loopback.io/doc/en/contrib/Reporting-issues.html)
12+
13+
Issues in [strongloop/loopback-next](https://github.com/strongloop/loopback-next/issues) are the primary means by which bug reports and general discussions are made.
14+
15+
- [How to report an issue](http://loopback.io/doc/en/contrib/Reporting-issues.html#how-to-report-an-issue)
16+
- [Disclosing security vulnerabilities](http://loopback.io/doc/en/contrib/Reporting-issues.html#security-issues)
17+
18+
## [Contributing code](http://loopback.io/doc/en/contrib/code-contrib.html)
19+
20+
Pull Requests are the way concrete changes are made to the code, documentation
21+
and tools contained in LoopBack repositories.
22+
23+
- [Setting up development environment](./DEVELOPING.md#setting-up-development-environment)
24+
- [How to contribute the code](http://loopback.io/doc/en/contrib/code-contrib.html#how-to-contribute-to-the-code)
25+
- [Building the project](./DEVELOPING.md#building-the-project)
26+
- [Running tests](./DEVELOPING.md#running-tests)
27+
- [Coding rules](./DEVELOPING.md#coding-rules)
28+
- [API documentation](./DEVELOPING.md#api-documentation)
29+
- [Git commit messages](./DEVELOPING.md#commit-message-guidelines)
30+
- [Reviewing pull requests](http://loopback.io/doc/en/contrib/triaging-pull-requests.html)
31+
- [Contributor License Agreement (CLA)](http://loopback.io/doc/en/contrib/code-contrib.html#agreeing-to-the-cla)
32+
33+
## [Documentation](http://loopback.io/doc/en/contrib/doc-contrib.html)
34+
35+
LoopBack documentation is sourced in the [strongloop/loopback.io](https://github.com/strongloop/loopback.io) GitHub repository.
36+
37+
- [How LoopBack documentation works](http://loopback.io/doc/en/contrib/doc-contrib.html#how-loopback-documentation-works)
38+
- [Using Jekyll](http://loopback.io/doc/en/contrib/jekyll_getting_started.html)
39+
- [Authoring pages](http://loopback.io/doc/en/contrib/pages.html)
40+
- [Translations](http://loopback.io/doc/en/contrib/translation.html)
41+

‎docs/DEVELOPING.md

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Developing LoopBack
2+
3+
This document describes how to develop modules living in loopback-next monorepo.
4+
5+
- [Setting up development environment](#setting-up-development-environment)
6+
- [Building the project](#building-the-project)
7+
- [Running tests](#running-tests)
8+
- [Coding rules](#coding-rules)
9+
- [API documentation](#api-documentation)
10+
- [Commit message guidelines](#commit-message-guidelines)
11+
- [How to test infrastructure changes](#how-to-test-infrastructure-changes)
12+
13+
## Setting up development environment
14+
15+
Before you can start developing LoopBack, you need to install and configure few
16+
dependencies.
17+
18+
- [git](https://git-scm.com/): Github's [Set Up Git](https://help.github.com/articles/set-up-git/) guide is a good source of information.
19+
- [Node.js 8.x (LTS)](https://nodejs.org/en/download/)
20+
21+
You may want to configure your IDE or editor to get better support for
22+
TypeScript too.
23+
24+
- [VisualStudio Code](./VSCODE.md)
25+
- _Missing your favorite IDE/editor here? Pull requests are welcome!_
26+
27+
Before getting started, it is recommended to configure `git` so that it knows who you are:
28+
29+
```sh
30+
$ git config --global user.name "J. Random User"
31+
$ git config --global user.email "[email protected]"
32+
```
33+
34+
Please make sure this local email is also added to your [GitHub email list](https://github.com/settings/emails) so that your commits will be properly associated with your account and you will be promoted to Contributor once your first commit is landed.
35+
36+
## Building the project
37+
38+
Whenever you pull updates from GitHub or switch between feature branches,
39+
we recommend to do a full reinstall of all npm dependencies:
40+
41+
```sh
42+
$ npm run clean:lerna && npm run bootstrap
43+
```
44+
45+
The next step is to compile all packages from TypeScript to JavaScript:
46+
47+
```sh
48+
$ npm run build
49+
```
50+
51+
Please note that we are automatically running the build from `pretest`
52+
script, therefore you should not need to run this command as part of your
53+
[red-green-refactor cycle](http://www.jamesshore.com/Blog/Red-Green-Refactor.html).
54+
55+
## Running tests
56+
57+
This is the only command you should need while developing LoopBack:
58+
59+
```sh
60+
$ npm test
61+
```
62+
63+
It does all you need:
64+
65+
- Compile TypeScript
66+
- Run all tests
67+
- Check code formatting using [Prettier](https://prettier.io/)
68+
- Lint the code using [TSLint](https://palantir.github.io/tslint/)
69+
70+
## Coding rules
71+
72+
- All features and bug fixes must be covered by one or more automated tests.
73+
74+
- All public methods must be documented with typedoc comments (see [API Documentation](#api-documentation) below).
75+
76+
- Code should be formatted using [Prettier](https://prettier.io/), see our [prettierrc](../prettierrc).
77+
78+
- Follow our style guide as documented on loopback.io: [Code style guide](http://loopback.io/doc/en/contrib/style-guide.html).
79+
80+
## API Documentation
81+
82+
We use [strong-docs](https://github.com/strongloop/strong-docs) to generate API documentation for all our packages. This documentation is generated when publishing new releases to npmjs.org and it's picked up by http://apidocs.loopback.io/.
83+
84+
You can preview API docs locally by opening the file `docs/apidocs.html` in your browser.
85+
86+
## Commit message guidelines
87+
88+
A good commit message should describe what changed and why.
89+
90+
Our commit messages are formatted according to [Conventional Commits](https://conventionalcommits.org/), we use [commitlint](https://github.com/marionebl/commitlint) to verify and enforce this convention. These rules lead to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate change logs when publishing new versions.
91+
92+
### Commit Message Format
93+
94+
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special format that includes a **type**, an optional **scope** and a **subject**:
95+
96+
```
97+
<type>(<scope>): <subject>
98+
<BLANK LINE>
99+
<body>
100+
<BLANK LINE>
101+
<footer>
102+
```
103+
104+
#### type
105+
106+
The **type** must be one of the following:
107+
108+
- **feat**: A new feature
109+
- **fix**: A bug fix
110+
- **docs**: Documentation only changes
111+
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
112+
- **refactor**: A code change that neither fixes a bug nor adds a feature
113+
- **perf**: A code change that improves performance
114+
- **test**: Adding missing or correcting existing tests
115+
- **build**: Changes that affect the build system or external dependencies
116+
- **ci**: Changes to our CI configuration files and scripts
117+
- **chore**: Changes to the auxiliary tools and libraries such as documentation generation
118+
- **revert**: Reverts a previous commit
119+
120+
#### scope
121+
122+
The **scope** must be a list of one or more packages contained in this monorepo. Eeach scope name must match a directory name in [packages/](../packages), e.g. `core` or `context`.
123+
124+
125+
#### subject
126+
127+
The **subject** contains succinct description of the change:
128+
129+
- use the imperative, present tense: "change" not "changed" nor "changes"
130+
- don't capitalize first letter
131+
- no dot (.) at the end
132+
133+
#### body
134+
135+
The **body** provides more details, it should include the motivation for the change and contrast this with previous behavior.
136+
137+
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes"a
138+
139+
#### footer (optional)
140+
141+
The **footer** should contain any information about Breaking Changes introduced by this commit.
142+
143+
This section must start with the upper case text `BREAKING CHANGE` followed by a colon (`:`) and a space (` `). A description must be provided, describing what has changed and how to migrate from older versions.
144+
145+
## How to test infrastructure changes
146+
147+
When making changes to project infrastructure, e.g. modifying `tsc` or `tslint`
148+
configuration, it's important to verify that all usage scenarios keep working.
149+
150+
### Verify TypeScript setup
151+
152+
1. Open any existing TypeScript file, e.g. `packages/src/index.ts`
153+
154+
2. Add a small bit of code to break TypeScript's type checks, for example:
155+
156+
```ts
157+
const foo: number = 'bar';
158+
```
159+
160+
3. Run `npm test`
161+
162+
4. Verify that the build failed and the compiler error message shows a path
163+
relative to monorepo root, e.g. `packages/src/index.ts`.
164+
165+
_(2018-02-82: this is does not work now, `tsc` is reporting paths relative to individual package directories.)_
166+
167+
5. Test integration with supported IDEs:
168+
- [VS Code](./VSCode.md#how-to-verify-typescript-setup)
169+
170+
### Verify TSLint setup
171+
172+
1. Open any existing TypeScript file, e.g. `packages/src/index.ts`
173+
174+
2. Introduce two kinds linting problems - one that does and another that does not require type information to be detected. For example, you can add the following line at the end of the opened `index.ts`:
175+
176+
```ts
177+
const foo: any = 'bar';
178+
```
179+
180+
3. Run `npm test`
181+
182+
4. Verify that the build failed and both linting problems are reported:
183+
184+
```text
185+
ERROR: /Users/(...)/packages/core/src/index.ts[16, 7]: 'foo' is declared but its value is never read.
186+
ERROR: /Users/(...)/packages/core/src/index.ts[16, 12]: Type declaration of 'any' loses type-safety. Consider replacing it with a more precise type.
187+
```
188+
189+
5. Test integration with supported IDEs:
190+
191+
- [VS Code](./VSCode.md#how-to-verify-tslint-setup)
192+

‎docs/VSCODE.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Developing with VisualStudio Code
2+
3+
We recommend our contributors to use [VisualStudio Code](https://code.visualstudio.com/) with the following extensions installed:
4+
- [Prettier - Code Formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for automatic formatting of source files on save.
5+
- [TSLint](https://marketplace.visualstudio.com/items?itemName=eg2.tslint) to highlight and auto-fix linting problems directly in the editor.
6+
7+
Our monorepo comes with few preconfigured [VSCode
8+
Tasks](https://code.visualstudio.com/docs/editor/tasks):
9+
10+
- The build task is configured to run the TypeScript compiler
11+
- The test task is configured to run `npm test` (which runs the build before running any tests).
12+
13+
## How to verify TypeScript setup
14+
15+
### Compilation errors
16+
17+
1. Open any existing TypeScript file, e.g. `packages/src/index.ts`
18+
19+
2. Add a small bit of code to break TypeScript's type checks, for example:
20+
21+
```ts
22+
const foo: number = 'bar';
23+
```
24+
25+
3. Verify that VS Code editor has marked `foo` with a red underscore. Hover over `foo` and check the problem message. It should mention `[ts]` source, e.g.
26+
27+
```text
28+
[ts] Type '"bar"' is not assignable to type 'number'.
29+
30+
```
31+
32+
4. Check VS Code's [PROBLEMS Window](https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_errors-and-warnings). There should be an entry showing the same tslint error. When you click on the entry, it should jump on the problematic line.
33+
34+
5. Close the editor tab. (This will clear the PROBLEMS entry reported by TSLint extension).
35+
36+
6. Run the test task ("Tasks: Run test task"). This will invoke package scripts like `npm test` under the hood.
37+
38+
7. Open "Tasks" OUTPUT window and verify that compilation error was parsed by VSCode.
39+
40+
8. Verify that compilation errors are correctly associated with the problematic source code line.
41+
_(2018-02-82: this is does not work now, `tsc` is reporting paths relative to individual package directories.)_
42+
43+
### Navigation in VS Code
44+
45+
Verify that "Go to definition" works across package boundaries. Find a place where we are calling `@inject` in `authentication` package, press F12 to go to the definition of `inject`. VSCode should jump to the `.ts` file in `src` (as opposed to jumping to a `.d.ts` file in `dist`)
46+
47+
#### Refactoring in VS Code
48+
49+
Verify that refactorings like "rename" will change all places using the renamed entity. Two different scenarios to verify: rename at the place where the entity is defined, rename at the place where the entity is used. (You can e.g. rename `inject` to test.)
50+
51+
## How to verify TSLint setup
52+
53+
1. Open any existing TypeScript file, e.g. `packages/src/index.ts`
54+
55+
2. Verify that TSLint extension is not reporting any warnings in the output
56+
window:
57+
- pres _Cmd+shift+P_ or _Ctrl+shift+P_ to open task selector
58+
- find and run the task `TSLint: Show Output`
59+
- check the logs
60+
61+
An example of a warning we want to **avoid**:
62+
63+
```text
64+
Warning: The 'no-unused-variable' rule requires type information.
65+
```
66+
67+
3. Introduce two kinds linting problems - one that does and another that does not require type information to be detected. For example, you can add the following line at the end of the opened `index.ts`:
68+
69+
```ts
70+
const foo: any = 'bar';
71+
```
72+
73+
4. Verify that VS Code editor has marked `any` with a red underscore. Hover over `any` and check the problem message. It should mention `no-any` rule, e.g.
74+
75+
```text
76+
[tslint] Type declaration of 'any' loses type-safety. Consider replacing it with a more precise type. (no-any)
77+
```
78+
79+
5. Check VS Code's [PROBLEMS Window](https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_errors-and-warnings). There should be an entry showing the same tslint error. When you click on the entry, it should jump on the problematic line.
80+
81+
6. Close the editor tab. (This will clear the PROBLEMS entry reported by TSLint extension).
82+
83+
7. Run the test task ("Tasks: Run test task"). This will invoke package scripts like `npm test` under the hood.
84+
85+
8. Open "Tasks" OUTPUT window and verify that two tslint problems were reported:
86+
87+
```text
88+
ERROR: /Users/(...)/packages/core/src/index.ts[16, 7]: 'foo' is declared but its value is never read.
89+
ERROR: /Users/(...)/packages/core/src/index.ts[16, 12]: Type declaration of 'any' loses type-safety. Consider replacing it with a more precise type.
90+
```
91+
92+
9. Open "PROBLEMS" window again. Verify that both problems were parsed by VS Code and are correctly associated with the problematic source code line.
93+

‎docs/apidocs.html

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<html>
2+
<head>
3+
<meta charset="utf-8">
4+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
5+
<title>LoopBack API Documentation (local)</title>
6+
<link rel="stylesheet" href="http://apidocs.loopback.io/css/bootstrap.min.css">
7+
<link rel="stylesheet" href="http://apidocs.loopback.io/css/code-themes/sl-theme.css">
8+
<link rel="stylesheet" href="http://apidocs.loopback.io/css/main.css">
9+
</head>
10+
<body>
11+
<div class="col-lg-9 reset-home-content">
12+
<div id="LoopBack4">
13+
<h2>LoopBack4 packages (local)</h2>
14+
15+
<p>Run the following command to (re)build API doc files:
16+
<p><pre><code>$ lerna run build:apidocs</code></pre>
17+
18+
<h3>List of packages</h3>
19+
<ul>
20+
<li><a href="../packages/authentication/api-docs/index.html">@loopback/authentication</a></li>
21+
<li><a href="../packages/context/api-docs/index.html">@loopback/context</a></li>
22+
<li><a href="../packages/core/api-docs/index.html">@loopback/core</a></li>
23+
<li><a href="../packages/metadata/api-docs/index.html">@loopback/metadata</a></li>
24+
<li><a href="../packages/openapi-spec/api-docs/index.html">@loopback/openapi-spec</a></li>
25+
<li><a href="../packages/openapi-spec-builder/api-docs/index.html">@loopback/openapi-spec-builder</a></li>
26+
<li><a href="../packages/openapi-v2/api-docs/index.html">@loopback/openapi-v2</a></li>
27+
<li><a href="../packages/repository/api-docs/index.html">@loopback/repository</a></li>
28+
<li><a href="../packages/rest/api-docs/index.html">@loopback/rest</a></li>
29+
</ul>
30+
</div>
31+
</div>
32+
</body>
33+
</html>

0 commit comments

Comments
 (0)