Skip to content

Commit

Permalink
docs: update contributing guide (#2475)
Browse files Browse the repository at this point in the history 
* docs: update contributing guide

* docs: add yarn init option

* fix: markdown linting errors
  • Loading branch information
@bencodezen
bencodezen committed Jul 19, 2020
1 parent 9b9049a commit 823c1df
Showing 1 changed file with 123 additions and 51 deletions.
174 changes: 123 additions & 51 deletions packages/docs/docs/miscellaneous/local-development.md
View file
Expand Up @@ -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)

0 comments on commit 823c1df

Please sign in to comment.