Skip to content

Latest commit

 

History

History
181 lines (117 loc) · 6.24 KB

DEV-README.md

File metadata and controls

181 lines (117 loc) · 6.24 KB
Raw

Collaboration samples dev documentation

The main component of the samples maintenance are various scripts streamlining the whole process. Scripts are located in the _scripts directory.

Most of the scripts does not require ckeditor5* repositories, however _scripts/build.js depends (internally) on ckeditor5 package utils. Thus, the suggested directory structure on your file system looks like on the following snippet:

workspace/
├── ckeditor5
└── ckeditor5-collaboration-samples

Table of contents

Dependencies management

There are 2 scripts dedicated to help with dependencies management.

check-dependencies

This script checks all samples dependencies, whether:

  • All dependencies are used,
  • All dependencies are up-to-date.

If there are any unused or outdated dependencies, the script will output a list of such for each sample.

It can be run with:

yarn samples:check-dependencies

And accepts following flags:

  • --verbose (-v) - adds more logging,
  • --sample (-s) - checks only given sample (full name needs to be passed).

Internally, this script uses depcheck and npm-check-updates packages.

IMPORTANT: The depcheck library does not work perfectly with Angular and so it may complain about unused deps which are in fact needed. This false positive usually looks as below:

Executed command: npx depcheck

Unused dependencies
* @angular/compiler
* @angular/forms
* zone.js
Unused devDependencies
* @angular-devkit/build-angular
* @angular/cli
* @angular/compiler-cli
* typescript

update-dependencies

This script updates samples dependencies. It allows for:

  • Updating all dependencies.
  • Updating only CKEditor 5 dependencies (ckeditor5, ckeditor5-premium-features and integrations packages).

It can be run with:

yarn samples:update-dependencies

And accepts following flags:

  • --verbose (-v) - adds more logging,
  • --sample (-s) - updates only given sample,
  • --commit (-c) - commits all changes generated by the script,
  • --ckeditor-only - updates only CKEditor 5 related dependencies.

ProTip: This script (with --ckeditor-only flag) is run by release script, so it does not have to be run separately in normal circumstances.

Building

There are 2 scripts dedicated for samples building. The main goal is to allow smoother development, easier testing of multiple samples and use as a part of the CI check.

Building is no longer used as a part of the release process as before. Only sources are published.

build

This scripts builds all samples in a separate directory. The end result is a directory with only build outputs for each sample (no source files).

It requires ckeditor5 package, so one should follow suggested directory structure mentioned on the beginning of this document, or use --ckeditor5-path CLI argument to pass the custom localization.

yarn samples:build --ckeditor5-path /home/user/workspace/ckeditor/ckeditor5

This script can be run with:

yarn samples:build

And accepts following flags:

  • --verbose (-v) - adds more logging,
  • --sample (-s) - builds only given sample,
  • --dev (-d) - installs latest nightly versions of CKEditor 5 packages from npm instead of using the ones from samples' package.json file,
  • --concurrency (-c) - defines how many samples will be build concurrently,
  • --keep (-k) - indicates whether the release directory should not be removed before starting the build,
  • --ckeditor5-path - defines a path to the ckeditor/ckeditor5 repository.

The building script always call the yarn install command. Passing the --dev option uses latest nightly versions of CKEditor 5 packages.

It generates build in the build/release-collaboration-samples/ directory. After that, one can easily run all samples at once with:

cd build/release-collaboration-samples/ && http-server

build-local

This scripts runs build process for each sample separately. It is like doing cd sample_dir && yarn && yarn build for all samples at once.

It can be run with:

yarn samples:build-local

And accepts following flags:

  • --verbose (-v) - adds more logging,
  • --sample (-s) - builds only given sample,
  • --concurrency (-c) - defines how many samples will be build concurrently.

Releasing

The release process involves mostly updating ckeditor5* dependencies in all samples and pushing it to the remote. No build artifacts should be published as a part of it (as it was in the past).

The entire release process involves following steps:

  1. Creating a tag for current version (where tag name is v{CURRENT_CKEDITOR5_DEP_VERSION}).
  2. Updating ckeditor5* dependencies for all samples on master branch.
  3. Pushing the tag and master to the remote.

There is a dedicated release script to streamline the whole process, which covers 1st and 2nd step described above.

Before starting the release, make sure that:

  1. The ckeditor5, ckeditor5-premium-features and/or integration packages have been released (check npm).
  2. You are on the master branch with latest changes and no local modifications.

After that you can proceed with the release using release script as described in the section below.

As a post-release actions, make sure to:

  1. Notify on #cke5-release that the release has been done: "Collaboration samples have been released 🎉".

release

This script helps with the release process, doing most of the work.

It can be run with:

yarn samples:release

And accepts following flags:

  • --verbose (-v) - adds more logging.

The result of running the script is a new commit with ckeditor5* dependencies updated for all samples and a new git tag.

If there are any local modification, existing git tag with the same name or ckeditor5* dependencies not updated, the script will abort.