Ver Fonte

Docs: Backported updates to the dev env docs.

Piotrek Koszuliński há 7 anos atrás
pai
commit
f5c2872e95
1 ficheiros alterados com 71 adições e 55 exclusões
  1. 71 55
      docs/framework/guides/contributing/development-environment.md

+ 71 - 55
docs/framework/guides/contributing/development-environment.md

@@ -8,7 +8,7 @@ order: 10
 The CKEditor 5 codebase is divided into multiple [npm](http://npmjs.com/) packages, each developed in a separate Git repository. The main package is [`ckeditor5`](https://github.com/ckeditor/ckeditor5) which installs all project dependencies and various development-related resources such as:
 
 * the testing environment setup,
-* configuration for [mgit](https://www.npmjs.com/package/mgit2) (a multi-repo management tool) and [Lerna.js](https://github.com/lerna/lerna) (a multi-package management tool),
+* configuration for [mgit](https://www.npmjs.com/package/mgit2) (a multi-repo management tool) and [Yarn](https://yarnpkg.com/) (a dependency management tool),
 * translation management tools,
 * documentation generator,
 * and release tools.
@@ -20,23 +20,22 @@ You can find all the official packages listed in [CKEditor 5 development reposit
 In order to start developing CKEditor 5 you will require:
 
 * [Node.js](https://nodejs.org/en/) 6.9.0+
-* npm 4+ (**note:** some npm 5+ versions were known to cause [problems](https://github.com/npm/npm/issues/16991), especially with deduplicating packages; upgrade npm when in doubt)
 * [Git](https://git-scm.com/)
 
 ## Setting up the CKEditor development environment
 
 First, you need to install a couple of tools which you will be using later:
 
-* [mgit](https://www.npmjs.com/package/mgit2) – A multi-repo management tool,
-* [Lerna.js](https://github.com/lerna/lerna)@2 – A multi-package management tool. Note: Lerna@3 is [not supported yet](https://github.com/ckeditor/ckeditor5/issues/1214).
+* [mgit2](https://www.npmjs.com/package/mgit2) — A multi-repo management tool,
+* [Yarn](https://yarnpkg.com/) — A dependency management tool.
 
 It is best to install them globally in your system for an easier use later on:
 
 ```bash
-npm install -g lerna@2 mgit2
+npm install -g yarn mgit2
 ```
 
-Note: You may need to use `sudo` on Linux and macOS.
+**Note:** [Read how to avoid using `sudo` to install packages globally](https://github.com/sindresorhus/guides/blob/master/npm-global-without-sudo.md) or use [nvm](https://github.com/creationix/nvm).
 
 Then clone the [main repository](https://github.com/ckeditor/ckeditor5):
 
@@ -50,21 +49,19 @@ And install all CKEditor 5 packages from the [npm registry](http://npmjs.com/).
 **Note:** If you plan to use the developement version of CKEditor 5 packages (see the [next section](#switching-to-development-version-of-packages)), you can skip this step to save time.
 
 ```bash
-npm install
+yarn install
 ```
 
-This may take a [while](https://github.com/npm/npm/issues/10380)...
-
 ### Switching to development version of packages
 
 The steps above should install all the packages from npm, which means that you will have the latest releases of all of them. They are available in `node_modules/@ckeditor/` (we are using [scoped packages](https://docs.npmjs.com/misc/scope), hence the unusual directory).
 
-In order to work with development versions of all the official packages, it is recommended to use mgit and Lerna. The former will clone all package repositories and the latter will be able to symlink them, so they create a correct directory structure, understandable by Node.js-compliant tools (like webpack or Browserify).
+In order to work with development versions of all the official packages, it is recommended to use mgit. This tool will clone all package repositories to the `packages/` directory. Then, those packages need to be installed in a way understandable by Node.js-compliant tools (like webpack or Browserify). In order to achieve that we use Yarn's feature called [workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) which creates symlinks to these packages.
 
 First, clone all the repositories:
 
 ```bash
-mgit bootstrap
+mgit sync
 ```
 
 Expected result:
@@ -79,30 +76,57 @@ packages/
 └── ckeditor5-utils
 ```
 
-Finally, link them:
+Finally, install all external dependencies (such as the test runner) and create symlinks to CKEditor 5 packages available in the `packages/` directory with this one command:
 
 ```bash
-lerna bootstrap
+yarn install
 ```
 
-Running Lerna may take a while because it installs all package dependencies. It will also warn you about circular dependencies between packages which you can ignore.
-
-Now, all CKEditor packages (except the [development tools](https://github.com/ckeditor/ckeditor5-dev)) should be cross-symlinked:
+You can check that CKEditor 5 packages which are part of the development environment (so those except [development tools](https://github.com/ckeditor/ckeditor5-dev) and some closed source packages) should be linked:
 
 ```bash
-(master 340feac) p@m /workspace/ckeditor5> ls -la node_modules/\@ckeditor/ckeditor5-utils/node_modules/\@ckeditor/
-total 16
-drwxr-xr-x    5 p  staff   170 31 Jan 10:37 .
-drwxr-xr-x  292 p  staff  9928 20 Jan 00:20 ..
-lrwxr-xr-x    1 p  staff    23 31 Jan 10:37 ckeditor5-core -> ../../../ckeditor5-core
-drwxr-xr-x    7 p  staff   238 20 Jan 00:20 ckeditor5-dev-docs
-lrwxr-xr-x    1 p  staff    25 31 Jan 10:37 ckeditor5-engine -> ../../../ckeditor5-engine
+(master ae6f43a) p@m /workspace/misc/ckeditor5> ls -la node_modules/\@ckeditor/
+total 0
+drwxr-xr-x    54 p  staff   1728 11 sty 14:41 .
+drwxr-xr-x  1115 p  staff  35680 11 sty 14:41 ..
+drwxr-xr-x     7 p  staff    224 11 sty 14:41 ckeditor-cloud-services-collaboration
+drwxr-xr-x     6 p  staff    192 11 sty 14:41 ckeditor-cloud-services-core
+lrwxr-xr-x     1 p  staff     41 11 sty 14:41 ckeditor5-adapter-ckfinder -> ../../packages/ckeditor5-adapter-ckfinder
+lrwxr-xr-x     1 p  staff     34 11 sty 14:41 ckeditor5-alignment -> ../../packages/ckeditor5-alignment
+lrwxr-xr-x     1 p  staff     35 11 sty 14:41 ckeditor5-autoformat -> ../../packages/ckeditor5-autoformat
+lrwxr-xr-x     1 p  staff     33 11 sty 14:41 ckeditor5-autosave -> ../../packages/ckeditor5-autosave
+lrwxr-xr-x     1 p  staff     37 11 sty 14:41 ckeditor5-basic-styles -> ../../packages/ckeditor5-basic-styles
+lrwxr-xr-x     1 p  staff     36 11 sty 14:41 ckeditor5-block-quote -> ../../packages/ckeditor5-block-quote
+lrwxr-xr-x     1 p  staff     38 11 sty 14:41 ckeditor5-build-balloon -> ../../packages/ckeditor5-build-balloon
+lrwxr-xr-x     1 p  staff     38 11 sty 14:41 ckeditor5-build-classic -> ../../packages/ckeditor5-build-classic
+lrwxr-xr-x     1 p  staff     49 11 sty 14:41 ckeditor5-build-decoupled-document -> ../../packages/ckeditor5-build-decoupled-document
+lrwxr-xr-x     1 p  staff     37 11 sty 14:41 ckeditor5-build-inline -> ../../packages/ckeditor5-build-inline
+lrwxr-xr-x     1 p  staff     33 11 sty 14:41 ckeditor5-ckfinder -> ../../packages/ckeditor5-ckfinder
+lrwxr-xr-x     1 p  staff     34 11 sty 14:41 ckeditor5-clipboard -> ../../packages/ckeditor5-clipboard
+lrwxr-xr-x     1 p  staff     39 11 sty 14:41 ckeditor5-cloud-services -> ../../packages/ckeditor5-cloud-services
+drwxr-xr-x     7 p  staff    224 11 sty 14:41 ckeditor5-collaboration-core
+drwxr-xr-x     7 p  staff    224 11 sty 14:41 ckeditor5-comments
+lrwxr-xr-x     1 p  staff     29 11 sty 14:41 ckeditor5-core -> ../../packages/ckeditor5-core
+drwxr-xr-x     8 p  staff    256 11 sty 14:41 ckeditor5-dev-docs
+drwxr-xr-x     9 p  staff    288 11 sty 14:41 ckeditor5-dev-env
+drwxr-xr-x     9 p  staff    288 11 sty 14:41 ckeditor5-dev-tests
+drwxr-xr-x     8 p  staff    256 11 sty 14:41 ckeditor5-dev-utils
+drwxr-xr-x     8 p  staff    256 11 sty 14:41 ckeditor5-dev-webpack-plugin
+lrwxr-xr-x     1 p  staff     35 11 sty 14:41 ckeditor5-easy-image -> ../../packages/ckeditor5-easy-image
+lrwxr-xr-x     1 p  staff     39 11 sty 14:41 ckeditor5-editor-balloon -> ../../packages/ckeditor5-editor-balloon
+lrwxr-xr-x     1 p  staff     39 11 sty 14:41 ckeditor5-editor-classic -> ../../packages/ckeditor5-editor-classic
+lrwxr-xr-x     1 p  staff     41 11 sty 14:41 ckeditor5-editor-decoupled -> ../../packages/ckeditor5-editor-decoupled
+lrwxr-xr-x     1 p  staff     38 11 sty 14:41 ckeditor5-editor-inline -> ../../packages/ckeditor5-editor-inline
+lrwxr-xr-x     1 p  staff     31 11 sty 14:41 ckeditor5-engine -> ../../packages/ckeditor5-engine
+lrwxr-xr-x     1 p  staff     30 11 sty 14:41 ckeditor5-enter -> ../../packages/ckeditor5-enter
+
+... and so on
 ```
 
 If everything worked correctly, you should be able to run some tests:
 
 ```bash
-npm run test -- --files=core
+yarn run test --files=core
 ```
 
 ### Fetching changes
@@ -114,51 +138,43 @@ Whenever you want to update all packages to their latest versions call:
 git pull
 
 # To update pull changes to all the packages:
-mgit update
+mgit sync
 ```
 
-From time to time, if the list of dependencies in any of the packages changed, you will need to call Lerna again to symlink them:
+From time to time, if the list of dependencies in any of the packages changed, you will need to call Yarn again to symlink them:
 
 ```bash
-lerna bootstrap
+yarn install
 ```
 
-You can also speed it up if you know which package has changed:
+### Working with multiple repositories
 
-```bash
-lerna bootstrap --scope=@ckeditor/ckeditor5-core
-```
+Mgit implements many useful commands, such as:
 
-### Using mgit for custom packages
+* `mgit exec 'command'` – executing a shell command in all repositories,
+* `mgit checkout <branch>` – checking all repositories to given branch (or hash),
+* `mgit status` – displaying information about all repositories.
 
-If you are developing custom packages or forked any of the official packages and want mgit to work with it, change the dependencies configuration in [`mgit.json`](https://github.com/ckeditor/ckeditor5/blob/master/mgit.json). Note that mgit is able to clone the package from any Git URL. Refer to [its documentation](https://github.com/cksource/mgit2) for more details.
+Read more about those commands in [mgit's documentation](https://github.com/cksource/mgit2).
 
-### Troubleshooting problems with Lerna
+Mgit has been developed by the [CKSource team](https://cksource.com/) and we are relying on it heavily, hence you can expect more features and improvements to come. However, it is not a CKEditor-specific tool and should be suitable for any multi-repository project (though it best fits JavaScript projects).
 
-Lerna does pretty complicated things on an already complicated npm ecosystem. If you happen to run into some issues when calling `lerna bootstrap`, here are some tips:
-
-* Look for `npm-debug.log` files in the main package and subpackages. They may point to an obvious issue like a typo in some `package.json`.
-* Sometimes repeating `lerna bootstrap` may help.
-* If nothing else works, do `lerna clean && lerna bootstrap`.
-
-### Final word about mgit and Lerna
-
-Besides the already mentioned features, mgit allows you to [execute shell commands](https://github.com/cksource/mgit2#exec) on all packages (e.g. check their status). It has been developed by the [CKSource team](https://cksource.com/) and we are relying on it heavily, hence you can expect more features and improvements to come. However, it is not a CKEditor-specific tool and should be suitable for any multi-repository project (though it best fits JavaScript projects).
+### Using mgit for custom packages
 
-Lerna is a tool used by many well-known projects such as [Babel.js](https://github.com/babel/babel). It has an amazing community and, relying on it ourselves, we hope that it will become a standard for managing multi-package projects.
+If you are developing custom packages or forked any of the official packages and want mgit to work with it, change the dependencies configuration in [`mgit.json`](https://github.com/ckeditor/ckeditor5/blob/master/mgit.json). Note that mgit is able to clone the package from any Git URL. Refer to [its documentation](https://github.com/cksource/mgit2) for more details.
 
 ## Running tests
 
 In order to run tests you need to use the `test` and `manual` tasks.
 
 ```bash
-npm test -- --watch --coverage --source-map --files=engine
+yarn run test --watch --coverage --source-map --files=engine
 ```
 
 or, shorter:
 
 ```bash
-npm test -- -wcs --files=engine
+yarn run test -- -wcs --files=engine
 ```
 
 This command will run the [`ckeditor5-engine`](https://github.com/ckeditor/ckeditor5-engine) package's tests.
@@ -168,7 +184,7 @@ This command will run the [`ckeditor5-engine`](https://github.com/ckeditor/ckedi
 To create a server for manual tests use the `manual` task:
 
 ```bash
-npm run manual
+yarn run manual
 ```
 
 It accepts the `--source-map` (`-s`) option. Note that it watches for changes in the JavaScript files only (see the [bug](https://github.com/ckeditor/ckeditor5-dev/issues/52)).
@@ -180,24 +196,24 @@ You can read more about the {@link framework/guides/contributing/testing-environ
 To build the documentation you need to run the `docs` task:
 
 ```bash
-npm run docs
+yarn run docs
 ```
 
 The documentation will be available in `build/docs/`.
 
 This task accepts the following arguments:
 
-* `--skip-api` &ndash; Skips building the API documentation (which takes the majority of the total time).
-* `--skip-snippets` &ndash; Skips building live snippets.
-* `--skip-validation` &ndash; Skips the final link validation.
-* `--watch` &ndash; Runs the documentation generator in a watch mode. It covers guides (it does not cover API docs).
-* `--production` &ndash; Minifies the assets and performs other actions which are unnecessary during CKEditor 5 development.
-* `--verbose` &ndash; Prints out more information.
+* `--skip-api` &mdash; Skips building the API documentation (which takes the majority of the total time).
+* `--skip-snippets` &mdash; Skips building live snippets.
+* `--skip-validation` &mdash; Skips the final link validation.
+* `--watch` &mdash; Runs the documentation generator in a watch mode. It covers guides (it does not cover API docs).
+* `--production` &mdash; Minifies the assets and performs other actions which are unnecessary during CKEditor 5 development.
+* `--verbose` &mdash; Prints out more information.
 
 Note: These arguments must be passed after additional `--`:
 
 ```
-npm run docs -- --skip-api
+yarn run docs --skip-api
 ```
 
 ## Bisecting through a multi-repository