diff --git a/.circleci/config.yml b/.circleci/config.yml index df8f510a4f..ab691f43f6 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,17 +1,54 @@ aliases: - - &restore-yarn-cache + - &root-yarn + | + yarn install --non-interactive --cache-folder ~/.cache/yarn + + - &root-restore-yarn-cache + keys: + - root-yarn-{{ .Branch }}-{{ checksum "yarn.lock" }} + # Fallback in case checksum fails + - root-yarn-{{ .Branch }}- + + - &root-save-yarn-cache + paths: + - node_modules + - ~/.cache/yarn + key: root-yarn-{{ .Branch }}-{{ checksum "yarn.lock" }} + + - &v1-yarn + | + cd v1 + yarn install --non-interactive --cache-folder ~/.cache/yarn + + - &v1-restore-yarn-cache keys: - v1-yarn-{{ .Branch }}-{{ checksum "yarn.lock" }} # Fallback in case checksum fails - v1-yarn-{{ .Branch }}- - - &save-yarn-cache + - &v1-save-yarn-cache paths: - - node_modules - v1/node_modules - ~/.cache/yarn key: v1-yarn-{{ .Branch }}-{{ checksum "yarn.lock" }} + - &v2-yarn + | + cd v2 + yarn install --non-interactive --cache-folder ~/.cache/yarn + + - &v2-restore-yarn-cache + keys: + - v2-yarn-{{ .Branch }}-{{ checksum "yarn.lock" }} + # Fallback in case checksum fails + - v2-yarn-{{ .Branch }}- + + - &v2-save-yarn-cache + paths: + - v2/node_modules + - ~/.cache/yarn + key: v2-yarn-{{ .Branch }}-{{ checksum "yarn.lock" }} + - &filter-only-master branches: only: @@ -21,12 +58,6 @@ aliases: branches: ignore: gh-pages - - &yarn - | - yarn install --non-interactive --cache-folder ~/.cache/yarn - cd v1 && - yarn install --non-interactive --cache-folder ~/.cache/yarn - defaults: &defaults working_directory: ~/docusaurus docker: @@ -35,16 +66,29 @@ defaults: &defaults version: 2 jobs: - tests: + prettier: <<: *defaults steps: - checkout - - restore-cache: *restore-yarn-cache - - run: *yarn - - save-cache: *save-yarn-cache + - restore-cache: *root-restore-yarn-cache + - run: *root-yarn + - save-cache: *root-save-yarn-cache - run: - name: Check Prettier & ESLint - command: cd v1 && yarn ci-check + name: Check Prettier + command: | + yarn install + yarn prettier:diff + + v1-tests: + <<: *defaults + steps: + - checkout + - restore-cache: *v1-restore-yarn-cache + - run: *v1-yarn + - save-cache: *v1-save-yarn-cache + - run: + name: Check ESLint + command: cd v1 && yarn lint - run: name: Run Test Suites command: cd v1 && yarn test @@ -52,15 +96,32 @@ jobs: name: Test Static Website Builds command: cd v1/website && yarn run build - # The CIRCLE_ variables are defined during the CircleCI build process - # https://circleci.com/docs/1.0/environment-variables/ - deploy-website: + v2-tests: <<: *defaults steps: - checkout - - restore-cache: *restore-yarn-cache - - run: *yarn - - save-cache: *save-yarn-cache + - restore-cache: *v2-restore-yarn-cache + - run: *v2-yarn + - save-cache: *v2-save-yarn-cache + - run: + name: Check ESLint + command: cd v2 && yarn lint + - run: + name: Run Test Suites + command: cd v2 && yarn test + - run: + name: Test Static Website Builds + command: cd v2/website && yarn run build + + # The CIRCLE_ variables are defined during the CircleCI build process + # https://circleci.com/docs/1.0/environment-variables/ + v1-deploy-website: + <<: *defaults + steps: + - checkout + - restore-cache: *v1-restore-yarn-cache + - run: *v1-yarn + - save-cache: *v1-save-yarn-cache - run: name: Configure GitHub Bot # Do not do this if we don't have the right org (facebook), or if this is just a pull request @@ -97,9 +158,9 @@ jobs: <<: *defaults steps: - checkout - - restore-cache: *restore-yarn-cache - - run: *yarn - - save-cache: *save-yarn-cache + - restore-cache: *v1-restore-yarn-cache + - run: *v1-yarn + - save-cache: *v1-save-yarn-cache - run: name: Publish Docusaurus Package command: | @@ -114,13 +175,18 @@ jobs: workflows: version: 2 - website: + prettier: jobs: - - tests: + - prettier: filters: *filter-ignore-gh-pages - - deploy-website: + + v1: + jobs: + - v1-tests: + filters: *filter-ignore-gh-pages + - v1-deploy-website: requires: - - tests + - v1-tests filters: *filter-only-master deploy: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9cc00f275c..ccf1021481 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,11 +10,11 @@ Facebook has adopted a Code of Conduct that we expect project participants to ad There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started: -* Simply start using Docusaurus. Go through the [Getting Started](https://docusaurus.io/docs/en/installation.html) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues). -* Look through the [open issues](https://github.com/facebook/docusaurus/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](#triaging-issues-and-pull-requests). -* If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started. -* Read through the [Docusaurus docs](https://docusaurus.io/docs/en/installation.html). If you find anything that is confusing or can be improved, you can make edits by clicking "Edit" at the top of most docs. -* Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on. +- Simply start using Docusaurus. Go through the [Getting Started](https://docusaurus.io/docs/en/installation.html) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues). +- Look through the [open issues](https://github.com/facebook/docusaurus/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](#triaging-issues-and-pull-requests). +- If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started. +- Read through the [Docusaurus docs](https://docusaurus.io/docs/en/installation.html). If you find anything that is confusing or can be improved, you can make edits by clicking "Edit" at the top of most docs. +- Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on. Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help. @@ -26,10 +26,10 @@ We have `#docusaurus-dev` on [Discord](https://discord.gg/docusaurus) to discuss One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in. -* Ask for more information if you believe the issue does not provide all the details required to solve it. -* Suggest [labels](https://github.com/facebook/docusaurus/labels) that can help categorize issues. -* Flag issues that are stale or that should be closed. -* Ask for test plans and review code. +- Ask for more information if you believe the issue does not provide all the details required to solve it. +- Suggest [labels](https://github.com/facebook/docusaurus/labels) that can help categorize issues. +- Flag issues that are stale or that should be closed. +- Ask for test plans and review code. ## Our development process @@ -57,13 +57,23 @@ You can also file issues as [feature requests or enhancements](https://github.co When [opening a new issue](https://github.com/facebook/docusaurus/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template. -* **One issue, one bug:** Please report a single bug per issue. -* **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort. +- **One issue, one bug:** Please report a single bug per issue. +- **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort. ### Security bugs Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page. +## Installation + +1. Ensure you have [Yarn](https://yarnpkg.com/) installed. +1. After cloning the repository, run `yarn install` in the root of the repository. + + - For Docusaurus 1 development, go into the `v1` directory and do `yarn install`. + - For Docusaurus 2 development, go into the `v2` directory and do `yarn install`. + +1. Run `yarn start` in the respective project directory to start a local development server serving the Docusaurus docs. + ## Pull requests ### Your first pull request @@ -93,8 +103,8 @@ Please make sure the following is done when submitting a pull request: 1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `master`. 1. Add the copyright notice to the top of any code new files you've added. 1. Describe your [**test plan**](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/Docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md)! -1. Make sure your code lints (`npm run prettier && npm run lint`). -1. Make sure our Jest tests pass (`npm run test`). +1. Make sure your code lints (`yarn prettier && yarn lint`). +1. Make sure your Jest tests pass (`yarn test`). 1. If you haven't already, [sign the CLA](https://code.facebook.com/cla). All pull requests should be opened against the `master` branch. @@ -103,7 +113,7 @@ All pull requests should be opened against the `master` branch. A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI. -* If you've changed APIs, update the documentation. +- If you've changed APIs, update the documentation. #### Breaking changes @@ -112,10 +122,10 @@ When adding a new breaking change, follow this template in your pull request: ```md ### New breaking change here -* **Who does this affect**: -* **How to migrate**: -* **Why make this breaking change**: -* **Severity (number of people affected x effort)**: +- **Who does this affect**: +- **How to migrate**: +- **Why make this breaking change**: +- **Severity (number of people affected x effort)**: ``` #### Copyright Notice for code files @@ -149,30 +159,17 @@ However, there are still some styles that Prettier cannot pick up. #### General -* **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming things in code, naming things in documentation. -* Add trailing commas, -* 2 spaces for indentation (no tabs) -* "Attractive" +- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation. +- "Attractive" #### JavaScript -* Use semicolons; -* ES6 standards -* Prefer `'` over `"` -* Do not use the optional parameters of `setTimeout` and `setInterval` -* 80 character line length - -#### JSX - -* Prefer `"` over `'` for string literal props -* When wrapping opening tags over multiple lines, place one prop per line -* `{}` of props should hug their values (no spaces) -* Place the closing `>` of opening tags on the same line as the last prop -* Place the closing `/>` of self-closing tags on their own line and left-align them with the opening `<` +- ES6 standards. Prefer using modern language features where they make the code better. +- Do not use the optional parameters of `setTimeout` and `setInterval` ### Documentation -* Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation. +- Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation. ## License diff --git a/README.md b/README.md index b5a73194c9..5fbf49b331 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ Docusaurus is a project for easily building, deploying, and maintaining open source project websites. -* **Simple to Start** Docusaurus is built to be easy to [get up and running](https://docusaurus.io/docs/en/installation.html) in as little time possible. We've built Docusaurus to handle the website build process so you can focus on your project. -* **Localizable** Docusaurus ships with [localization support](https://docusaurus.io/docs/en/translation.html) via CrowdIn. Empower and grow your international community by translating your documentation. -* **Customizable** While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/en/blog.html), and additional support pages, it is also [customizable](https://docusaurus.io/docs/en/custom-pages.html) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/en/api-pages.html). +- **Simple to Start** Docusaurus is built to be easy to [get up and running](https://docusaurus.io/docs/en/installation.html) in as little time possible. We've built Docusaurus to handle the website build process so you can focus on your project. +- **Localizable** Docusaurus ships with [localization support](https://docusaurus.io/docs/en/translation.html) via CrowdIn. Empower and grow your international community by translating your documentation. +- **Customizable** While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a [blog](https://docusaurus.io/docs/en/blog.html), and additional support pages, it is also [customizable](https://docusaurus.io/docs/en/custom-pages.html) as well to ensure you have a site that is [uniquely yours](https://docusaurus.io/docs/en/api-pages.html). ## Installation @@ -54,9 +54,7 @@ We have a few channels for contact: ## Contributors -This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)]. - - +This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)]. ## Backers @@ -64,15 +62,11 @@ Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com - ## Sponsors Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/Docusaurus#sponsor)] - - - - + ## License diff --git a/package.json b/package.json index 7cc9f52367..d58cc7276c 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "url": "https://github.com/facebook/Docusaurus.git" }, "scripts": { - "ci-check": "yarn prettier && cd v1 && yarn ci-check", + "precommit": "lint-staged", "prettier": "prettier --config .prettierrc --write \"**/*.js\"", "prettier:diff": "prettier --config .prettierrc --list-different \"**/*.js\"", "start": "cd v1/website && yarn start" diff --git a/v1/package.json b/v1/package.json index 0dc44d8a44..23ad698e58 100644 --- a/v1/package.json +++ b/v1/package.json @@ -9,7 +9,6 @@ "url": "https://github.com/facebook/Docusaurus.git" }, "scripts": { - "ci-check": "yarn lint", "lint": "eslint --cache \"lib/**/*.js\" \"examples/**/*.js\" \"website/**/*.js\"", "test": "jest", "start": "cd website && yarn start" diff --git a/v2/package.json b/v2/package.json index b7f9643506..0f70dd57d7 100644 --- a/v2/package.json +++ b/v2/package.json @@ -7,7 +7,6 @@ "munseo": "bin/munseo.js" }, "scripts": { - "ci-check": "yarn lint", "munseo": "node bin/munseo", "start": "node bin/munseo start website", "build": "node bin/munseo build website",