Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switched development environment to Yarn #1345

Merged
merged 15 commits into from
Jan 10, 2019
16 changes: 8 additions & 8 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,25 @@ addons:
packages:
- google-chrome-stable
language: node_js
cache:
yarn: true
node_js:
- "8"
cache:
- node_modules
before_install:
- export DISPLAY=:99.0
- sh -e /etc/init.d/xvfb start
- npm config set package-lock false
- npm i -g npm@^5.7.1
- npm i -g yarn
install:
- npm install
- npm install mgit2 lerna
- yarn add mgit2 --ignore-workspace-root-check
- mgit bootstrap --resolver-url-template="https://github.com/\${ path }.git"
- lerna bootstrap
- yarn
script:
- npm t -- --reporter=dots
- npm run docs:api -- --validate-only
- yarn run test --reporter=dots
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can it be like this?

Suggested change
- yarn run test --reporter=dots
- yarn test --reporter=dots

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yarn allows to do it. But IMO it might be risky to do it in .travis file.

- yarn run docs:api --validate-only
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also no need to run.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I made a couple of suggestions here in this PR, but it'll be easier to change this automatically in all places. s/yarn run/yarn seems to work for me.

- 'if [ $TRAVIS_TEST_RESULT -eq 0 ]; then
travis_wait npm run docs:build-and-publish-nightly;
travis_wait yarn run docs:build-and-publish-nightly;
fi'
notifications:
slack:
Expand Down
2 changes: 1 addition & 1 deletion docs/builds/guides/development/custom-builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ After you changed the webpack entry file or updated some dependencies, it is tim
To do that, execute the following command:

```bash
npm run build
yarn run build
```

You can validate whether your new build works by opening the `sample/index.html` file in a browser (via HTTP, not as a local file). Make sure to **clear the cache**.
Expand Down
2 changes: 1 addition & 1 deletion docs/builds/guides/integration/advanced-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -560,7 +560,7 @@ index c57e371..04fc9fe 100644
Once you changed the `src/ckeditor.js` and `webpack.config.js` files it is time to rebuild the build:

```bash
npm run build
yarn run build
```

Finally, when webpack finishes compiling your super build, you can change the `samples/index.html` file to test both editors:
Expand Down
2 changes: 1 addition & 1 deletion docs/builds/guides/integration/installing-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ ClassicEditor.defaultConfig = {
Finally, bundle the build:

```bash
npm run build
yarn run build
```

If everything worked, the editor build (which is available in the `build/` directory) should be updated.
Expand Down
52 changes: 17 additions & 35 deletions docs/framework/guides/contributing/development-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -20,20 +20,20 @@ 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)
* [Yarn](https://yarnpkg.com/) 1.2.0+
* [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).
* [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.
Expand All @@ -50,16 +50,14 @@ 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. 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).

First, clone all the repositories:

Expand All @@ -82,10 +80,10 @@ packages/
Finally, link them:

```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.
Running Yarn may take a while because it installs all package dependencies.

Now, all CKEditor packages (except the [development tools](https://github.com/ckeditor/ckeditor5-dev)) should be cross-symlinked:

Expand All @@ -102,7 +100,7 @@ lrwxr-xr-x 1 p staff 25 31 Jan 10:37 ckeditor5-engine -> ../../../ckedito
If everything worked correctly, you should be able to run some tests:

```bash
npm run test -- --files=core
yarn run test --files=core
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
yarn run test --files=core
yarn test --files=core

```

### Fetching changes
Expand All @@ -117,48 +115,32 @@ git pull
mgit update
```

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:

```bash
lerna bootstrap
```

You can also speed it up if you know which package has changed:
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 --scope=@ckeditor/ckeditor5-core
yarn install
```

### Using mgit for custom packages

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.

### Troubleshooting problems with Lerna

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
### Final word about mgit

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).

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.

## 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
yarn run test --watch --coverage --source-map --files=engine
yarn 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.
Expand All @@ -168,7 +150,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)).
Expand All @@ -180,7 +162,7 @@ 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/`.
Expand All @@ -197,7 +179,7 @@ This task accepts the following arguments:
Note: These arguments must be passed after additional `--`:

```
npm run docs -- --skip-api
yarn run docs --skip-api
```

## Bisecting through a multi-repository
Expand Down
10 changes: 5 additions & 5 deletions docs/framework/guides/contributing/testing-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Each CKEditor package has its own tests suite (see for example the [engine's tes

## Running automated tests

In order to run the automated tests use the `npm test [-- <args>...]` command.
In order to run the automated tests use the `yarn run test [<args>...]` command.

It accepts the following arguments (must be passed after the `--` option):

Expand All @@ -31,24 +31,24 @@ It accepts the following arguments (must be passed after the `--` option):
Run all tests with the code coverage check of the [`ckeditor5-core`](https://github.com/ckeditor/ckeditor5-core) package:

```
npm test -- -c --files=core
yarn run test -c --files=core
```

Run and watch the [engine's `view` namespace tests](https://github.com/ckeditor/ckeditor5-engine/tree/master/tests/view) and all the tests in [`ckeditor5-typing`](https://github.com/ckeditor/ckeditor5-typing):

```
npm test -- -cw --files=engine/view,typing
yarn run test -cw --files=engine/view,typing
```

Run the `bold*.js` tests in the [`ckeditor5-basic-styles`](https://github.com/ckeditor/ckeditor5-basic-styles) package:

```
npm test -- -cw --files=basic-styles/bold*.js
yarn run test -cw --files=basic-styles/bold*.js
```

## Running manual tests

In order to start the manual tests server use the `npm run manual` task.
In order to start the manual tests server use the `yarn run manual` task.

The task accepts the `--source-map` (alias `-s`) option.

Expand Down
2 changes: 1 addition & 1 deletion docs/framework/guides/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ You can now run webpack to build the application. To do that, call the `webpack`
And use it via:

```bash
npm run build
yarn run build
```

npm adds `./node_modules/.bin/` to the `PATH` automatically, so in this case you do not need to install `webpack-cli` globally.
Expand Down
14 changes: 0 additions & 14 deletions lerna.json

This file was deleted.

4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,6 @@
"eslint-config-ckeditor5": "^1.0.7",
"glob": "^7.1.2",
"husky": "^0.14.3",
"lerna": "^2.2.0",
"lint-staged": "^7.0.0",
"mgit2": "^0.8.0",
"mini-css-extract-plugin": "^0.4.0",
Expand Down Expand Up @@ -129,5 +128,8 @@
"build/**",
"coverage/**",
"packages/**"
],
"workspaces": [
"packages/*"
]
}
2 changes: 1 addition & 1 deletion scripts/docs/build-and-publish-nightly.js
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ exec( `git clone ${ mainRepoUrl }.git` );

// Build the documentation.
console.log( 'Building documentation...' );
exec( 'npm run docs -- --production' );
exec( 'yarn run docs --production' );

console.log( 'Copying files...' );

Expand Down
2 changes: 1 addition & 1 deletion scripts/docs/build-and-publish.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ console.log( 'Updating your ckeditor5.github.io clone...' );
exec( 'cd ../ckeditor5.github.io && git pull && cd -' );

console.log( 'Building documentation...' );
exec( 'npm run docs -- --production' );
exec( 'yarn run docs --production' );

console.log( 'Copying files...' );

Expand Down
4 changes: 2 additions & 2 deletions scripts/release/bump-versions.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@
// You can test the whole process using `dry-run` mode. It won't change anything in the project
// and any repository.
//
// This task must be called before: `npm run release:publish`.
// This task must be called before: `yarn run release:publish`.
//
// Use:
// npm run release:bump-version -- --dry-run
// yarn run release:bump-version --dry-run

require( '@ckeditor/ckeditor5-dev-env' )
.bumpVersions( {
Expand Down
2 changes: 1 addition & 1 deletion scripts/release/changelog.js
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
'use strict';

// In order to use the same version for all packages (including builds and ckeditor5 itself), you can call:
// npm run changelog [newVersion]
// yarn run changelog [newVersion]

const devEnv = require( '@ckeditor/ckeditor5-dev-env' );
const commonOptions = {
Expand Down
4 changes: 2 additions & 2 deletions scripts/release/publish.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@
//
// Note: This task based on versions published on NPM and GitHub. If something went wrong, you can call this script one more time.
//
// This task should be executed after: `npm run release:bump-version`.
// This task should be executed after: `yarn run release:bump-version`.
//
// Use:
// npm run release:publish -- --dry-run
// yarn run release:publish --dry-run

/* eslint-disable max-len */

Expand Down
Loading