From cf65b0b2f575557002c1911f33e672998cf601ed Mon Sep 17 00:00:00 2001 From: Oscar Lorentzon Date: Thu, 26 Nov 2020 15:41:27 +0100 Subject: [PATCH] docs: update contribution guide Simplify contribution guide and add CLA. Remove run keyword from yarn commands. --- .github/CONTRIBUTING.md | 99 +++++++++++------------------------------ README.md | 2 +- package.json | 9 ++-- 3 files changed, 33 insertions(+), 77 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7c94d041..06b88b78 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,91 +2,46 @@ Thanks in advance for contributing to MapillaryJS. Please follow the conventions ## [Code of Conduct](https://code.facebook.com/codeofconduct) -The code of conduct is described in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) +Facebook has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](.CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated. -## Preparing your Development Environment +## Contribution Prerequisites +- You have [Node](https://nodejs.org) installed at v10.0.0+ and [Yarn](https://classic.yarnpkg.com) at v1.2.0+. +- You are familiar with Git. -### Linux +## Sending a Pull Request +We will review your pull request and either merge it, request changes to it, or close it with an explanation. We’ll do our best to provide updates and feedback throughout the process. -Install [GNU Make](http://www.gnu.org/software/make/) and [git](https://git-scm.com/): -```bash -sudo apt-get update && -sudo apt-get install build-essential git -``` +**Before submitting a pull request**, please make sure the following is done: -Install [node.js](https://nodejs.org/) _10.x_ and [npm](https://www.npmjs.com/) according to the [node.js package manager installation instructions](https://nodejs.org/en/download/package-manager/). +1. Fork [the repository](https://github.com/mapillary/mapillary-js) and create your branch from `master`. +2. Run `yarn` in the repository root. +3. If you’ve fixed a bug or added code that should be tested, add tests! +4. Ensure the test suite passes (`yarn test`). +5. Make sure your code lints (`yarn lint`). +6. If you haven’t already, complete the CLA. -Clone a copy of the repo: -```bash -git clone https://github.com/mapillary/mapillary-js.git -``` +## Contributor License Agreement (CLA) +In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you’ve done this for another Facebook open source project, you’re good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username. -Change to the mapillary-js directory and install node module dependencies: -```bash -cd mapillary-js && -npm install -``` +[Complete your CLA here.](https://code.facebook.com/cla) -### OSX -Install the Command Line Tools for Xcode: +## Development Workflow +After cloning MapillaryJS, run `yarn` to fetch its dependencies. Then, you can run several commands: -```bash -xcode-select --install -``` +- `yarn lint` checks the code style. +- `yarn test` runs the complete test suite. +- `yarn test-watch` runs an interactive test watcher. +- `yarn build` creates a `dist` folder with the package. +- `yarn build-docs` builds the documentation in the `docs/build` folder. -Install [Homebrew](http://brew.sh/) according to the instructions. +We recommend running `yarn test` to make sure you don’t introduce any regressions as you work on your change. -Install [node.js](https://nodejs.org/): -```bash -brew install node -``` +The easiest way to try your changes is to run `yarn start` and open the debug page at [http://localhost:3000](http://localhost:3000). -Clone a copy of the repo: -```bash -git clone https://github.com/mapillary/mapillary-js.git -``` +However it can be handy to try your build of MapillaryJS in a real project. First, run `yarn build`. This will produce pre-built bundles in the `dist` folder. -Change to the mapillary-js directory and install node module dependencies: -```bash -cd mapillary-js && -npm install -``` - -## Serving the Debug Page - -```bash -npm start -``` - -Open the debug page at [http://localhost:3000](http://localhost:3000). - -## Creating a Standalone Build - -A standalone build allows you to turn the MapillaryJS repository content into files that can be included on an html page. - -To create a standalone build, run - -```bash -npm prepare -``` - -Once that command finishes, you will have a standalone build at dist/mapillary.min.js and dist/mapillary.min.css together with the the dist/*.svg files. - -## Running Tests - -```bash -npm test -``` - -## Building and serving the documentation - -```bash -npm run build-docs && -python -m SimpleHTTPServer -```` - -Open the documentation page at [http://localhost:8000/docs/build](http://localhost:8000/docs/build). +If you want to try your changes in your existing project, you may copy `dist/mapillary.js`, `dist/mapillary.js.map`, and `dist/mapillary.min.css` into your app and use them instead of the stable version. ## Commit conventions diff --git a/README.md b/README.md index 10f67109..bfc042f5 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ Learn how to [contribute](./.github/CONTRIBUTING.md). ### [Code of Conduct](https://code.facebook.com/codeofconduct) -Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](./.github/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated. +Facebook has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](./.github/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated. ## License diff --git a/package.json b/package.json index 6cd8be3d..266f228f 100644 --- a/package.json +++ b/package.json @@ -79,24 +79,25 @@ "ie 11" ], "scripts": { + "build": "yarn build-dev && yarn build-min && yarn build-css", "build-css": "cat styles/*.css | postcss -o dist/mapillary.min.css", "build-dev": "browserify src/Mapillary.ts --plugin tsify --transform brfs --standalone Mapillary --debug | exorcist dist/mapillary.js.map > dist/mapillary.js", "build-docs": "typedoc --tsconfig tsconfig.docs.json --readme docs/landing.md --theme docs/theme/ --mode file --excludePrivate --excludeProtected --excludeExternals --name MapillaryJS --out docs/build/", "build-min": "browserify src/Mapillary.ts --plugin tsify --transform brfs --standalone Mapillary | uglifyjs -m > dist/mapillary.min.js", - "clean": "yarn run clean-dist && yarn run clean-docs", + "clean": "yarn clean-dist && yarn clean-docs", "clean-dist": "rm -rf dist && mkdir dist", "clean-docs": "rm -rf docs/build", - "lint": "yarn run lint-spec && yarn run lint-src", + "lint": "yarn lint-spec && yarn lint-src", "lint-spec": "tslint -c tslint.json -p tsconfig.json \"spec/**/*.ts\"", "lint-src": "tslint -c tslint.json -p tsconfig.json \"src/**/*.ts\"", - "prepare": "yarn run clean && yarn run lint && yarn run build-min && yarn run build-dev && yarn run build-css", + "prepare": "yarn clean && yarn lint && yarn build-min && yarn build-dev && yarn build-css", "start": "node server.js", "test": "karma start --single-run", "test-watch": "karma start" }, "husky": { "hooks": { - "pre-commit": "yarn run lint -q", + "pre-commit": "yarn lint -q", "pre-push": "yarn test -q" } }