Skip to content

Commit 823c1df

Browse files
authored
docs: update contributing guide (#2475)
* docs: update contributing guide * docs: add yarn init option * fix: markdown linting errors
1 parent 9b9049a commit 823c1df

File tree

1 file changed

+123
-51
lines changed

1 file changed

+123
-51
lines changed

packages/docs/docs/miscellaneous/local-development.md

+123-51
Original file line numberDiff line numberDiff line change
@@ -4,96 +4,168 @@ sidebar: auto
44

55
# Local Development
66

7-
## Information
7+
## Introduction
88

9-
If you here you may be interested in improving core VuePress.
9+
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!
1010

11-
VuePress is using a combo with [Yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [Lerna](https://github.com/lerna/lerna).
11+
## Prerequisites
1212

13-
## Init packages
13+
- [Node.js v12.x](https://nodejs.org/en/)\*
14+
- [Yarn v1.x](https://classic.yarnpkg.com/)
15+
16+
\*Node.js v10 should work as well, but other versions have not been verified.
17+
18+
## Setup Guide
19+
20+
In this guide, we will be using the following names to refer to the two projects you need to be successful:
21+
22+
- **VuePress Project**: This refers to your fork of the [official VuePress repository](https://github.com/vuejs/vuepress/)
23+
- **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
24+
25+
### VuePress Project Setup
26+
27+
1. Fork the [official VuePress repository](https://github.com/vuejs/vuepress/)
28+
1. Clone your fork onto your machine (e.g., `git clone ...`)
29+
1. Open your cloned project in a new terminal window
30+
1. Run the following commands:
1431

1532
```bash
16-
yarn // it will install dependencies of all packages
33+
# Install all dependencies in the project
34+
yarn
35+
36+
# Compile shared-utils TypeScript package into JavaScript
37+
yarn tsc
1738
```
1839

19-
`yarn` will use hoisting. What does it mean for you ?
40+
5. Verify there is no global installation of VuePress
2041

21-
It will regroup all dependencies in the workspace root and link all packages.
42+
```bash
43+
# Check global yarn packages
44+
yarn global list
2245

23-
Check the link by running the following command:
46+
# If it exists, remove global VuePress package
47+
yarn global remove vuepress
48+
```
49+
50+
6. Configure local VuePress Project to be the source of truth
2451

2552
```bash
26-
ls -la node_modules/@vuepress
53+
# Registers local VuePress project
54+
yarn register-vuepress
55+
56+
# If successful, you should see a message
57+
# like `success Registered "vuepress"`
2758
```
2859

29-
:::warning
30-
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.
31-
:::
60+
And with that, we’re ready to setup our VuePress Sandbox!
3261

33-
:::warning
34-
There is a special package you should have a look is @vuepress/shared-utils that are in typescript.
35-
:::
62+
### VuePress Sandbox Setup
3663

37-
After install everything it will run `yarn tsc`. This command will tell to @vuepress/shared-utils workspace to compile his js.
64+
1. In a separate terminal, create a new npm project.
3865

39-
:::warning
40-
From here if you are making change inside this package you will have to
41-
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
42-
:::
66+
```bash
67+
# Create a new folder
68+
mkdir vuepress-sandbox
4369

44-
## Link
70+
# Change directory to VuePress Sandbox
71+
cd vuepress-sandbox
4572

46-
Good from here you have everything ready. You need to link VuePress to your project.
73+
# Initalize a new npm project
74+
yarn init # or npm init
4775

48-
```bash
49-
yarn register-vuepress
76+
# You will be prompted to fill out a form
77+
# Since this is a sandbox environment,
78+
# feel free to just hit skip through it
79+
# by hitting enter until it completes setup!
5080
```
5181

52-
You will have something like this: `success Registered "vuepress".`
82+
2. Create a basic VuePress Sandbox site
5383

54-
It will link the package VuePress from `packages/vuepress`. You will have access to VuePress cli and packages.
84+
```bash
85+
# Create the folder where your site will live
86+
mkdir docs
5587

56-
They are declared in the `packages/vuepress/package.json`
88+
# Initialize it with a simple markdown file
89+
echo '# My VuePress Sandbox Site' > docs/index.md
90+
```
5791

58-
```js
92+
3. Add a script to `package.json` to start VuePress environment
93+
94+
```json{7}
5995
{
60-
"main": "index.js",
61-
///
62-
"bin": {
63-
"vuepress": "cli.js"
64-
}
65-
///
96+
"name": "vuepress-sandbox",
97+
"version": "1.0.0",
98+
"description": "",
99+
"main": "index.js",
100+
"scripts": {
101+
"dev": "vuepress dev docs",
102+
"test": "echo \"Error: no test specified\" && exit 1"
103+
},
104+
"author": "",
105+
"license": "ISC",
106+
"dependencies": {}
66107
}
67108
```
68109

69-
Now go to your project and run `yarn link vuepress`.
110+
4. Verify that the script does not work
70111

71-
You should have it `success Using linked package for "vuepress".`
112+
```bash
113+
# Run dev command
114+
yarn dev
72115

73-
## Unlink
116+
# You should receive an error indicating
117+
# that VuePress cannot be found.
118+
# This is a good thing!
119+
```
74120

75-
You may want to unlink everything. For it in the workspace root folder. Run
121+
5. Link your VuePress Project to your VuePress Sandbox
76122

77123
```bash
78-
yarn unregister-vuepress
124+
# Link VuePress Project
125+
yarn link vuepress
126+
127+
# You should see a message like
128+
# `success Using linked package for "vuepress"`
129+
```
130+
131+
6. Run your script again and it should work!
132+
133+
```bash
134+
# Start local dev environment
135+
yarn dev
79136
```
80137

81-
Now you can run `yarn unlink vuepress` into your project folder.
138+
And with that, you should have a fully functioning local VuePress development environment!
139+
140+
### Disable Local Development
82141

83-
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.
142+
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:
84143

85-
## BUGS / QA
144+
1. Navigate to your VuePress Project in the terminal
145+
1. Unregister your VuePress Project
146+
147+
```bash
148+
# Unregister VuePress Project
149+
yarn unregister-vuepress
150+
```
86151

87-
You will maybe find some difficulty with link. If you encounter something like `There's already a package called "vuepress" registered`.
88-
You already have VuePress registered:
152+
3. Navigate to your VuePress Sandbox in the terminal
153+
1. Remove dependency on local VuePress Project
89154

90-
- 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
91-
- 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`.
155+
```bash
156+
yarn unlink vuepress
157+
```
92158

93-
## More
159+
And that’s it! You can go back to regular development now!
94160

95-
You will have interesting commands available:
161+
## Notes
96162

97-
- `yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme)
98-
- `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)
99-
- `yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme)
163+
- `yarn` will use hoisting. What does it mean for you ?
164+
- It will regroup all dependencies in the workspace root and link all packages.
165+
- 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.
166+
- There is a special package you should have a look is @vuepress/shared-utils that are in TypeScript.
167+
- 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
168+
- You will have interesting commands available:
169+
- `yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme)
170+
- `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)
171+
- `yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme)

0 commit comments

Comments
 (0)