diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 578e41fb846e..22fd715b0834 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,7 @@ Issues in [strongloop/loopback-next](https://github.com/strongloop/loopback-next Pull Requests are the way concrete changes are made to the code, documentation and tools contained in LoopBack repositories. + - [Monorepo overview](./MONOREPO.md) - [Setting up development environment](./docs/DEVELOPING.md#setting-up-development-environment) - [How to contribute the code](http://loopback.io/doc/en/contrib/code-contrib.html#how-to-contribute-to-the-code) - [Building the project](./docs/DEVELOPING.md#building-the-project) diff --git a/MONOREPO.md b/MONOREPO.md index 1d3c014f5bed..7b58f0c506c4 100644 --- a/MONOREPO.md +++ b/MONOREPO.md @@ -1,106 +1,30 @@ -# loopback-next +# Monorepo overview -The [loopback-next](https://github.com/strongloop/loopback-next) repository uses -[lerna](https://lernajs.io/) to manage multiple packages for LoopBack 4. +The [loopback-next](https://github.com/strongloop/loopback-next) repository uses [lerna](https://lernajs.io/) to manage multiple packages for LoopBack 4. -## Packages + | Package | npm | Description | |-----------------------------------------------------------|-------------------------------|---------------------------| +|[authentication](packages/authentication) |@loopback/authentication | A component for authentication support | +|[boot](packages/boot) |@loopback/boot | Convention based Bootstrapper and Booters | |[build](packages/build) |@loopback/build | A set of common scripts and default configurations to build LoopBack 4 or other TypeScript modules | -|[testlab](packages/testlab) |@loopback/testlib | A collection of test utilities we use to write LoopBack tests | |[cli](packages/cli) |@loopback/cli | CLI for LoopBack 4 | -|[metadata](packages/metadata) |@loopback/metadata | Utilities to help developers implement TypeScript decorators, define/merge metadata, and inspect metadata | |[context](packages/context) |@loopback/context | Facilities to manage artifacts and their dependencies in your Node.js applications. The module exposes TypeScript/JavaScript APIs and decorators to register artifacts, declare dependencies, and resolve artifacts by keys. It also serves as an IoC container to support dependency injection. | |[core](packages/core) |@loopback/core | Define and implement core constructs such as Application and Component | -|[boot](packages/boot) |@loopback/boot | Convention based Bootstrapper and Booters | -|[openapi-spec](packages/openapi-spec) |@loopback/openapi-spec | TypeScript type definitions for OpenAPI Spec/Swagger documents | +|[example-getting-started](packages/example-getting-started)| _(private)_ | A basic tutorial for getting started with Loopback 4 | +|[example-hello-world](packages/example-hello-world) | _(private)_ | A simple hello-world application using LoopBack 4 | +|[example-log-extension](packages/example-log-extension) | _(private)_ | An example showing how to write a complex log extension for LoopBack 4 | +|[example-rpc-server](packages/example-rpc-server) | _(private)_ | An example RPC server and application to demonstrate the creation of your own custom server | +|[metadata](packages/metadata) |@loopback/metadata | Utilities to help developers implement TypeScript decorators, define/merge metadata, and inspect metadata | |[openapi-spec-builder](packages/openapi-spec-builder) |@loopback/openapi-spec-builder | Builders to create OpenAPI (Swagger) specification documents in tests | +|[openapi-spec](packages/openapi-spec) |@loopback/openapi-spec | TypeScript type definitions for OpenAPI Spec/Swagger documents | |[openapi-v2](packages/openapi-v2) |@loopback/openapi-v2 | Decorators that annotate LoopBack artifacts with OpenAPI v2 (Swagger) metadata and utilities that transform LoopBack metadata to OpenAPI v2 (Swagger) specifications| |[openapi-v3-types](packages/openapi-v3-types) |@loopback/openapi-v3-types | TypeScript type definitions for OpenAPI Specifications | -|[rest](packages/rest) |@loopback/rest | Expose controllers as REST endpoints and route REST API requests to controller methods | -|[repository](packages/repository) |@loopback/repository | Define and implement a common set of interfaces for interacting with databases| |[repository-json-schema](packages/repository-json-schema) |@loopback/repository-json-schema| Convert a TypeScript class/model to a JSON Schema | -|[authentication](packages/authentication) |@loopback/authentication | A component for authentication support | -|[example-hello-world](packages/example-hello-world) | | A simple hello-world application using LoopBack 4 | -|[example-getting-started](packages/example-getting-started)| | A basic tutorial for getting started with Loopback 4 | -|[example-log-extension](packages/example-log-extension) | | An example showing how to write a complex log extension for LoopBack 4 | -|[example-rpc-server](packages/example-rpc-server) | | An example RPC server and application to demonstrate the creation of your own custom server | - -## Working with the repository - -We use npm scripts declared in [package.json](package.json) to work with the -monorepo managed by lerna. - -### Set up the project -```sh -git clone https://github.com/strongloop/loopback-next.git -cd loopback-next -npm run bootstrap -``` - -### Common tasks - -| Task | Command | Description | -|------------------|-----------------------|-------------| -|Bootstrap packages|`npm run bootstrap` |Install npm dependencies for all packages and create symbolic links for intra-dependencies. It's required for the initial setup or the list of packages is changed | -|Build packages |`npm run build` |Transpile TypeScript files into JavaScript | -|Run tests |`npm test` |Clean, build, run mocha tests, and perform lint checks | -|Fix lint issues |`npm run lint:fix` |Fix lint issues, including tslint rules and prettier formatting | - -### Build a release - -When we are ready to tag and publish a release, run the following commands: -```sh -cd loopback-next -git checkout master -git pull -npm run release -``` - -The `release` script will automatically perform the tasks for all packages: - -- Clean up `node_modules` -- Install/link dependencies -- Transpile TypeScript files into JavaScript -- Run mocha tests -- Check lint (tslint and prettier) issues - -If all steps are successful, it prompts you to publish packages into npm repository. - -### Add a new package - -To add a new package, create a folder in [`packages`](packages) as the root directory of your module. For example, -```sh -cd loopback-next/packages -mkdir -``` -The package follows the node/npm module layout. You can use `npm init` or `lb4 extension` command to scaffold the module, copy/paste from an existing package, or manually add files including `package.json`. - -We have some configuration files at the top level (**loopback-next/**): - -- `.gitignore` -- `.prettierignore` -- `.nycrc.yml` - -For consistency across all packages, do not add them at package level unless specific customization is needed. - -Please also register the new package in the following files: -- Add the new package and your name as its owner in [CODEOWNERS](CODEOWNERS). -- Add the new module in the `packages` list in [MONOREPO#packages](MONOREPO#packages). - -By default, npm publishes scoped packages with private access. There are two options to make a new scoped package with public access. +|[repository](packages/repository) |@loopback/repository | Define and implement a common set of interfaces for interacting with databases| +|[rest](packages/rest) |@loopback/rest | Expose controllers as REST endpoints and route REST API requests to controller methods | +|[testlab](packages/testlab) |@loopback/testlib | A collection of test utilities we use to write LoopBack tests | -Add the following section to `package.json`: -```json - "publishConfig": { - "access": "public" - }, -``` -Explicitly publish the package with --access=public. -```sh -cd packages/ -npm publish --access=public -``` +We use npm scripts declared in [package.json](package.json) to work with the monorepo managed by lerna. See [Developing LoopBack](./docs/DEVELOPING.md) for more details. -Make sure you add LICENSE file properly and all the files are began with copyrights declaration. \ No newline at end of file diff --git a/README.md b/README.md index 942d001aff07..6daabbe5e9d6 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,6 @@ LoopBack makes it easy to build modern applications that require complex integra - Define your data and endpoints with OpenAPI - No maintenance of generated code -# Work with this repository - -This repository uses [lerna](https://lernajs.io/) to manage multiple packages/modules -for LoopBack 4. Please see [MONOREPO.md](MONOREPO.md) for instructions to work with this monorepo. - # Status: Developer Preview #1 LoopBack 4 is a work in progress, the public API is frequently changed in @@ -33,7 +28,7 @@ Then in your Node.js project root, run: npm install -S @loopback/core ``` -> Make sure you set `"target": "es6"` in your compiler options in your +> Make sure you set `"target": "es2017"` in your compiler options in your > `tsconfig.json` if you're using a TypeScript project. See [Installation > ](http://loopback.io/doc/en/lb4/Installation.html) for > detailed information. @@ -61,11 +56,21 @@ To create your first LoopBack 4 application, See [Getting Started](http://loopba # Documentation - [Official documentation](http://loopback.io/doc/en/lb4/) -- [API documentation](http://apidocs.loopback.io/) +- [API documentation](http://apidocs.loopback.io/#LoopBack4) - [FAQ](http://loopback.io/doc/en/lb4/FAQ.html) - [LoopBack 3 vs LoopBack 4](http://loopback.io/doc/en/lb4/LoopBack-3.x.html) - [Tutorials and examples](http://loopback.io/doc/en/lb4/Examples-and-tutorials.html) +# Contributing + +See the following resources to get your started: + + - [Contributing Guidelines](./CONTRIBUTING.md) + - [Monorepo overview](./MONOREPO.md) + - [Developing LoopBack](./docs/DEVELOPING.md) + +You can join the team by posting a comment to [issue #110](https://github.com/strongloop/loopback-next/issues/110.). + # Team ## Project Architects: @@ -85,12 +90,6 @@ Raymond Feng|Miroslav Bajtos|Ritchie Martori|Kevin Delisle See [all contributors](https://github.com/strongloop/loopback-next/graphs/contributors). -# Contributing - -- [Working with this repository](MONOREPO.md) -- [Guidelines](https://github.com/strongloop/loopback-next/wiki/Contributing#guidelines) -- [Join the team](https://github.com/strongloop/loopback-next/issues/110) - # License [MIT](LICENSE) diff --git a/docs/DEVELOPING.md b/docs/DEVELOPING.md index 2752e9dd74eb..f27e10965872 100644 --- a/docs/DEVELOPING.md +++ b/docs/DEVELOPING.md @@ -1,6 +1,6 @@ # Developing LoopBack -This document describes how to develop modules living in loopback-next monorepo. +This document describes how to develop modules living in loopback-next monorepo. See [Monorepo overview](../MONOREPO.md) for a list of all packages. - [Setting up development environment](#setting-up-development-environment) - [Building the project](#building-the-project) @@ -8,6 +8,8 @@ This document describes how to develop modules living in loopback-next monorepo. - [Coding rules](#coding-rules) - [API documentation](#api-documentation) - [Commit message guidelines](#commit-message-guidelines) + - [Releasing new versions](#releasing-new-versions) + - [Adding a new package](#adding-a-new-package) - [How to test infrastructure changes](#how-to-test-infrastructure-changes) ## Setting up development environment @@ -35,11 +37,10 @@ Please make sure this local email is also added to your [GitHub email list](http ## Building the project -Whenever you pull updates from GitHub or switch between feature branches, -we recommend to do a full reinstall of all npm dependencies: +Whenever you pull updates from GitHub or switch between feature branches, make sure to updated installed dependencies in all monorepo packages. The following command will install npm dependencies for all packages and create symbolic links for intra-dependencies: ```sh -$ npm run clean:lerna && npm run bootstrap +$ npm run bootstrap ``` The next step is to compile all packages from TypeScript to JavaScript: @@ -73,10 +74,27 @@ It does all you need: - All public methods must be documented with typedoc comments (see [API Documentation](#api-documentation) below). -- Code should be formatted using [Prettier](https://prettier.io/), see our [prettierrc](../prettierrc). - - Follow our style guide as documented on loopback.io: [Code style guide](http://loopback.io/doc/en/contrib/style-guide.html). +### Linting and formatting + +We use two tools to keep our codebase healthy: + + - [TSLint](https://palantir.github.io/tslint/) to statically analyse our source code and detect common problems. + - [Prettier](https://prettier.io/) to keep our code always formatted the same way, avoid style discussions in code reviews, and save everybody's time an energy. + +You can run both linters via the following npm script, just keep in mind that `npm test` is already running them for you. + +```sh +$ npm run lint +``` + +Many problems (especially formatting) can be automatically fixed by running the npm script `lint:fix`. + +```sh +$ npm run lint:fix +``` + ## API Documentation 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/. @@ -123,6 +141,7 @@ The **type** must be one of the following: The **scope** must be a list of one or more packages contained in this monorepo. Each scope name must match a directory name in [packages/](../packages), e.g. `core` or `context`. +_Note: If multiple packages are affected by a pull request, don't list the scopes as the commit linter currently only supports only one scope being listed at most. The `CHANGELOG` for each affected package will still show the commit. Commit linter will be updated to allow listing of multiple affected scopes, see [issue #581](https://github.com/strongloop/loopback-next/issues/581)_ #### subject @@ -138,12 +157,96 @@ The **body** provides more details, it should include the motivation for the cha Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes"a +Paragraphs or bullet points are ok (must not exceed 100 characters per line). Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between. + #### footer (optional) The **footer** should contain any information about Breaking Changes introduced by this commit. 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. +### Tools to help generate a commit message + +This repository has [commitizen](https://github.com/commitizen/cz-cli) support enabled. Commitizen can help you generate your commit messages automatically. You must install it globally as follows: + +```sh +$ npm i -g commitizen +``` + +And to use it, simply call `git cz` instead of `git commit`. The tool will help you generate a commit message that follows the above guidelines. + +## Releasing new versions + +When we are ready to tag and publish a release, run the following commands: + +```sh +$ cd loopback-next +$ git checkout master +$ git pull +$ npm run release +``` + +The `release` script will automatically perform the tasks for all packages: + +- Clean up `node_modules` +- Install/link dependencies +- Transpile TypeScript files into JavaScript +- Run mocha tests +- Check lint (tslint and prettier) issues + +If all steps are successful, it prompts you to publish packages into npm repository. + +## Adding a new package + +### Create a new package + +To add a new package, create a folder in [`packages`](packages) as the root directory of your module. For example, +```sh +$ cd loopback-next/packages +$ mkdir +``` + +The package follows the node/npm module layout. You can use `npm init` or `lb4 extension` command to scaffold the module, copy/paste from an existing package, or manually add files including `package.json`. + +Make sure you add LICENSE file properly and all source code files have the correct copyright header. + +### Keep shared configuration in root + +We have some configuration files at the top level (**loopback-next/**): + +- `.gitignore` +- `.prettierignore` +- `.nycrc.yml` + +For consistency across all packages, do not add them at package level unless specific customization is needed. + +### Make a scoped package public + +By default, npm publishes scoped packages with private access. There are two options to make a new scoped package with public access. + +Either add the following section to `package.json`: +```json + "publishConfig": { + "access": "public" + }, +``` + +Or explicitly publish the package with `--access=public`: + +```sh +$ cd packages/ +$ npm publish --access=public +``` + +### Register the new package + +Please register the new package in the following files: + + - Update [MONOREPO.md](../MONOREPO.md) - insert a new table row to describe the new package, please keep the rows sorted by package name. + - Update [docs/apidocs.html](./docs/apidocs.html) - add a link to API docs for this new package. + - Update [CODEOWNERS](./CODEOWNERS) - add a new entry listing the primary maintainers (owners) of the new package + - Ask somebody from the IBM team (e.g. [@bajtos](https://github.com/bajtos), [@raymondfeng](https://github.com/raymondfeng) or [@kjdelisle](https://github.com/kjdelisle)) to enlist the new package on http://apidocs.loopback.io/ + ## How to test infrastructure changes When making changes to project infrastructure, e.g. modifying `tsc` or `tslint`