From 823c1dfd2d51cfc224ce6e3d5a70e9bcc776935f Mon Sep 17 00:00:00 2001 From: Ben Hong Date: Sun, 19 Jul 2020 03:03:16 -0400 Subject: [PATCH] docs: update contributing guide (#2475) * docs: update contributing guide * docs: add yarn init option * fix: markdown linting errors --- .../docs/miscellaneous/local-development.md | 174 +++++++++++++----- 1 file changed, 123 insertions(+), 51 deletions(-) diff --git a/packages/docs/docs/miscellaneous/local-development.md b/packages/docs/docs/miscellaneous/local-development.md index 006d51242a..5c70590e7f 100644 --- a/packages/docs/docs/miscellaneous/local-development.md +++ b/packages/docs/docs/miscellaneous/local-development.md @@ -4,96 +4,168 @@ sidebar: auto # Local Development -## Information +## Introduction -If you here you may be interested in improving core VuePress. +When it comes to contributing to an open-source project, the biggest obstacle people encounter is trying to get a local environment setup so they can test their changes to make sure everything works as expected. As a result, we have written this guide to help you so you can begin contributing to the VuePress ecosystem! -VuePress is using a combo with [Yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [Lerna](https://github.com/lerna/lerna). +## Prerequisites -## Init packages +- [Node.js v12.x](https://nodejs.org/en/)\* +- [Yarn v1.x](https://classic.yarnpkg.com/) + +\*Node.js v10 should work as well, but other versions have not been verified. + +## Setup Guide + +In this guide, we will be using the following names to refer to the two projects you need to be successful: + +- **VuePress Project**: This refers to your fork of the [official VuePress repository](https://github.com/vuejs/vuepress/) +- **VuePress Sandbox**: This refers to a local instance of VuePress that will serve as the simulation for creating test scenarios to verify that changes in the VuePress Project work as expected + +### VuePress Project Setup + +1. Fork the [official VuePress repository](https://github.com/vuejs/vuepress/) +1. Clone your fork onto your machine (e.g., `git clone ...`) +1. Open your cloned project in a new terminal window +1. Run the following commands: ```bash - yarn // it will install dependencies of all packages +# Install all dependencies in the project +yarn + +# Compile shared-utils TypeScript package into JavaScript +yarn tsc ``` -`yarn` will use hoisting. What does it mean for you ? +5. Verify there is no global installation of VuePress -It will regroup all dependencies in the workspace root and link all packages. +```bash +# Check global yarn packages +yarn global list -Check the link by running the following command: +# If it exists, remove global VuePress package +yarn global remove vuepress +``` + +6. Configure local VuePress Project to be the source of truth ```bash - ls -la node_modules/@vuepress +# Registers local VuePress project +yarn register-vuepress + +# If successful, you should see a message +# like `success Registered "vuepress"` ``` -:::warning -You have to take care to declare all dependencies inside subFolders package.json. When publish the lib if dependencies from a package is not declare it will just not work. -::: +And with that, we’re ready to setup our VuePress Sandbox! -:::warning -There is a special package you should have a look is @vuepress/shared-utils that are in typescript. -::: +### VuePress Sandbox Setup -After install everything it will run `yarn tsc`. This command will tell to @vuepress/shared-utils workspace to compile his js. +1. In a separate terminal, create a new npm project. -:::warning -From here if you are making change inside this package you will have to -run `yarn tsc` all the time or run in separate shell `yarn run tsc -w`. This will re run tsc at any change from shared-utils -::: +```bash +# Create a new folder +mkdir vuepress-sandbox -## Link +# Change directory to VuePress Sandbox +cd vuepress-sandbox -Good from here you have everything ready. You need to link VuePress to your project. +# Initalize a new npm project +yarn init # or npm init -```bash -yarn register-vuepress +# You will be prompted to fill out a form +# Since this is a sandbox environment, +# feel free to just hit skip through it +# by hitting enter until it completes setup! ``` -You will have something like this: `success Registered "vuepress".` +2. Create a basic VuePress Sandbox site -It will link the package VuePress from `packages/vuepress`. You will have access to VuePress cli and packages. +```bash +# Create the folder where your site will live +mkdir docs -They are declared in the `packages/vuepress/package.json` +# Initialize it with a simple markdown file +echo '# My VuePress Sandbox Site' > docs/index.md +``` -```js +3. Add a script to `package.json` to start VuePress environment + +```json{7} { -"main": "index.js", -/// -"bin": { - "vuepress": "cli.js" - } - /// + "name": "vuepress-sandbox", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "dev": "vuepress dev docs", + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + "dependencies": {} } ``` -Now go to your project and run `yarn link vuepress`. +4. Verify that the script does not work -You should have it `success Using linked package for "vuepress".` +```bash +# Run dev command +yarn dev -## Unlink +# You should receive an error indicating +# that VuePress cannot be found. +# This is a good thing! +``` -You may want to unlink everything. For it in the workspace root folder. Run +5. Link your VuePress Project to your VuePress Sandbox ```bash -yarn unregister-vuepress +# Link VuePress Project +yarn link vuepress + +# You should see a message like +# `success Using linked package for "vuepress"` +``` + +6. Run your script again and it should work! + +```bash +# Start local dev environment +yarn dev ``` -Now you can run `yarn unlink vuepress` into your project folder. +And with that, you should have a fully functioning local VuePress development environment! + +### Disable Local Development -If everything work properly you should have an error telling you there is no package found called vuepress, if you run `yarn link vuepress` in you project folder. +While it’s great that you can work with a local instance of VuePress, there will be times that you want to disable it so that you can refer to the published version instead. To do this, you will need to do the following: -## BUGS / QA +1. Navigate to your VuePress Project in the terminal +1. Unregister your VuePress Project + +```bash +# Unregister VuePress Project +yarn unregister-vuepress +``` -You will maybe find some difficulty with link. If you encounter something like `There's already a package called "vuepress" registered`. -You already have VuePress registered: +3. Navigate to your VuePress Sandbox in the terminal +1. Remove dependency on local VuePress Project -- If you already link VuePress from [Link](#link). It’s totally fine. If you make changes because it is symlink you dont have to re run something. You will have to rerun yarn tsc if you update shared-utils package. Nothing more -- If you didn’t do anything. You already have VuePress linked somewhere. What you have to do is deleting folder where you ran `yarn link` or `yarn unlink`. +```bash +yarn unlink vuepress +``` -## More +And that’s it! You can go back to regular development now! -You will have interesting commands available: +## Notes -- `yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme) -- `yarn packages:changed` will tell you which package will be affect by the next lerna publish / version [More...](https://github.com/lerna/lerna/tree/master/commands/changed#readme) -- `yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme) +- `yarn` will use hoisting. What does it mean for you ? + - It will regroup all dependencies in the workspace root and link all packages. +- You have to take care to declare all dependencies inside subFolders package.json. When publish the lib if dependencies from a package is not declare it will just not work. +- There is a special package you should have a look is @vuepress/shared-utils that are in TypeScript. + - From here if you are making change inside this package you will have to run `yarn tsc` all the time or run in separate shell `yarn run tsc -w`. This will re run tsc at any change from shared-utils +- You will have interesting commands available: + - `yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme) + - `yarn packages:changed` will tell you which package will be affect by the next lerna publish / version [More...](https://github.com/lerna/lerna/tree/master/commands/changed#readme) + - `yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme)