diff --git a/README.md b/README.md index 17aec6e2c08..5d5cfd4d726 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,6 @@ A set of ready-to-use rich text editors created with a powerful framework. Made ![CKEditor 5 Classic rich text editor build screenshot](https://c.cksource.com/a/1/img/npm/ckeditor5-build-classic.png) -## ⚠ This package does not contain any source code - -CKEditor 5 is distributed as [several ready-to-use rich text editor builds](https://ckeditor.com/docs/ckeditor5/latest/builds/guides/overview.html#available-builds) which you can [install from npm](https://ckeditor.com/docs/ckeditor5/latest/builds/guides/integration/installation.html#npm). - -You can also [customize the existing builds](https://ckeditor.com/docs/ckeditor5/latest/builds/guides/development/custom-builds.html) or build your own editors and features by using the [CKEditor 5 Framework](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/overview.html). - ## Table of contents * [Quick start](#quick-start) @@ -113,11 +107,11 @@ For a high-level overview of the project see the [CKEditor Ecosystem website](ht ### Ideas and discussions -The main development repository of CKEditor 5 is located at [https://github.com/ckeditor/ckeditor5](https://github.com/ckeditor/ckeditor5). This is the best place for bringing opinions and contributions. Letting the core team know if they are going in the right or wrong direction is great feedback and will be much appreciated! +The development repository of CKEditor 5 is located at [https://github.com/ckeditor/ckeditor5](https://github.com/ckeditor/ckeditor5). This is the best place for bringing opinions and contributions. Letting the core team know if they are going in the right or wrong direction is great feedback and will be much appreciated! ### Development -CKEditor 5 is a modular, multi-package, multi-repository project. It consists of several packages that create the editing framework, based on which the feature packages are implemented. +CKEditor 5 is a modular, multi-package, [monorepo](https://en.wikipedia.org/wiki/Monorepo) project. It consists of several packages that create the editing framework, based on which the feature packages are implemented. The [ckeditor5](https://github.com/ckeditor/ckeditor5) repository is the place that centralizes the development of CKEditor 5. It bundles different packages into a single place, adding the necessary helper tools for the development workflow, like the builder and the test runner. [Basic information on how to set up the development environment](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/development-environment.html) can be found in the documentation. diff --git a/docs/builds/guides/support/getting-support.md b/docs/builds/guides/support/getting-support.md index 158d2ff68eb..f245a02e4fb 100644 --- a/docs/builds/guides/support/getting-support.md +++ b/docs/builds/guides/support/getting-support.md @@ -9,8 +9,6 @@ order: 30 You can report issues and feature requests on [GitHub](https://github.com/ckeditor/ckeditor5). This is also a good place to discuss architecture decisions and things which are not yet covered by the documentation. -[Each CKEditor 5 repository](https://github.com/ckeditor?utf8=%E2%9C%93&q=ckeditor5&type=&language=) handles its issues independently. If you are not sure where your ticket belongs, it is best to report it in the [main repository](https://github.com/ckeditor/ckeditor5). - Refer to {@link builds/guides/support/reporting-issues Reporting issues} guide for more details. ## Stack Overflow diff --git a/docs/builds/guides/support/reporting-issues.md b/docs/builds/guides/support/reporting-issues.md index c12c7abce25..72f9411265b 100644 --- a/docs/builds/guides/support/reporting-issues.md +++ b/docs/builds/guides/support/reporting-issues.md @@ -22,7 +22,12 @@ Most of the issues are reproducible on the demo. If you have a different case th ## Reporting issues -All issues should be reported in the [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues) on GitHub. +All issues should be reported in the [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues) on GitHub, except ones that are related to one of the following projects (which have their own issue pages): + +* [Angular integration](https://github.com/ckeditor/ckeditor5-angular), +* [React integration](https://github.com/ckeditor/ckeditor5-react), +* [Vue integration](https://github.com/ckeditor/ckeditor5-vue), +* [CKEditor 5 inspector](https://github.com/ckeditor/ckeditor5-inspector). Things to keep in mind: diff --git a/docs/framework/guides/contributing/contributing.md b/docs/framework/guides/contributing/contributing.md index f9485190613..f7fa6702088 100644 --- a/docs/framework/guides/contributing/contributing.md +++ b/docs/framework/guides/contributing/contributing.md @@ -41,21 +41,25 @@ Read more about our {@link framework/guides/contributing/testing-environment tes GitHub provides an [excellent documentation about pull requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/). If you are not sure what to do, this is the right place to start. -Assuming that you would like to propose some changes in the [Link](https://github.com/ckeditor/ckeditor5-link) feature, these are the steps you should take to create a pull request: + + [Angular](https://github.com/ckeditor/ckeditor5-angular), [React](https://github.com/ckeditor/ckeditor5-react) and [Vue](https://github.com/ckeditor/ckeditor5-vue) integrations as well as [CKEditor 5 inspector](https://github.com/ckeditor/ckeditor5-inspector) and [dev packages](https://github.com/ckeditor/ckeditor5-dev) are kept in separate repositories. The below steps assume that you want to propose a change in the [main CKEditor 5 repository](https://github.com/ckeditor/ckeditor5). + + +Assuming that you would like to propose some changes, these are the steps you should take to create a pull request: -1. Make sure to open a ticket describing the issue/feature/problem that you want to solve in your pull request. This can be skipped in case of obvious and trivial changes (typos, documentation, etc.). You can report this ticket in the specific repository in which you will make a pull request or in https://github.com/ckeditor/ckeditor5. +1. Make sure to open a ticket in https://github.com/ckeditor/ckeditor5 describing the issue/feature/problem that you want to solve in your pull request. This can be skipped in case of obvious and trivial changes (typos, documentation, etc.). 1. Make sure your {@link framework/guides/contributing/development-environment development environment} is ready. -1. Go to GitHub and [fork the repository](https://help.github.com/articles/fork-a-repo) ([ckeditor5-link](https://github.com/ckeditor/ckeditor5-link) in this particular case). The forked repository will appear in your GitHub account as `https://github.com/YOUR-USERNAME/ckeditor5-link`. +1. Go to GitHub and [fork the repository](https://help.github.com/articles/fork-a-repo). The forked repository will appear in your GitHub account as `https://github.com/YOUR-USERNAME/ckeditor5`. 1. Open your terminal, then go to the package ("repository") folder in your development environment: ```shell - $ cd path/to/ckeditor5/packages/ckeditor5-link + $ cd path/to/ckeditor5 ``` -1. Start a new branch for your code. We use the `t/GITHUB-ISSUE-NUMBER` convention for branch names: +1. Start a new branch for your code. We use the `i/GITHUB-ISSUE-NUMBER` convention for branch names: ```shell - $ git checkout -b t/GITHUB-ISSUE-NUMBER + $ git checkout -b i/GITHUB-ISSUE-NUMBER ``` 1. Make the changes. Stick to the [code-style guidelines](#code-style) and remember about [tests and 100% code coverage](#tests)! @@ -68,13 +72,13 @@ Assuming that you would like to propose some changes in the [Link](https://githu 1. Now it is time to make your changes public. First, you need to let `git` know about the fork you created by adding the remote: ```shell - $ git remote add my-fork https://github.com/YOUR-USERNAME/ckeditor5-link + $ git remote add my-fork https://github.com/YOUR-USERNAME/ckeditor5 ``` 1. Push your changes to your forked repository: ```shell - $ git push my-fork t/GITHUB-ISSUE-NUMBER + $ git push my-fork i/GITHUB-ISSUE-NUMBER ``` 1. Go to your forked repository on GitHub. Use the [pull request button](https://help.github.com/articles/about-pull-requests/) and follow the instructions. Make sure to include a merge commit message text matches the {@link framework/guides/contributing/git-commit-message-convention convention} @@ -86,10 +90,6 @@ Some additional things you should keep in mind: * When making a pull request on GitHub, make sure to specify which ticket(s) your pull request resolves. It is also recommended to provide more information, like how to test the patch, issues that you encountered, decisions you had to make, known problems, etc. * Make sure you signed the [Contributor License Agreement (CLA)](#contributor-license-agreement-cla) and that tests pass. Test your changes! - - If want your changes to be permanent in your development environment, make sure your `mrgit.json` file {@link framework/guides/contributing/development-environment#using-mrgit-for-custom-packages points to your forked version of the repository} so next time you execute `mrgit sync` to refresh the project, the utility will use your fork. - - ## Translating CKEditor 5 is a project with global impact, so contributing translations is both an easy and powerful way to help. diff --git a/docs/framework/guides/contributing/development-environment.md b/docs/framework/guides/contributing/development-environment.md index ad3b320b837..9690b0068ed 100644 --- a/docs/framework/guides/contributing/development-environment.md +++ b/docs/framework/guides/contributing/development-environment.md @@ -5,39 +5,42 @@ order: 10 # Development environment -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 CKEditor 5 codebase is divided into multiple [npm](http://npmjs.com/) packages. 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 [Mr. Git](https://www.npmjs.com/package/mrgit) (a multi-repo management tool) and [Yarn](https://yarnpkg.com/) (a dependency management tool), +* configuration for [Yarn](https://yarnpkg.com/), * translation management tools, * documentation generator, * and release tools. +The main package's GitHub repository also [hosts all other CKEditor5 sub-packages](https://github.com/ckeditor/ckeditor5/tree/master/packages). + You can find all the official packages listed in [CKEditor 5 development repository's README](https://github.com/ckeditor/ckeditor5#packages). + +Prior to version **19.0.0** CKEditor 5 was developed in a multi repository architecture. If you'd like to work with the older multi-repository release, please refer to [older Developer Environment guide](/docs/ckeditor5/19.0.0/framework/guides/contributing/development-environment.html) for multi-repository oriented instructions. + + ## Requirements In order to start developing CKEditor 5 you will require: -* [Node.js](https://nodejs.org/en/) 6.9.0+ +* [Node.js](https://nodejs.org/en/) 8.0.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: +First, you need to install [Yarn](https://yarnpkg.com/) that will be used for dependency management. -* [mrgit](https://www.npmjs.com/package/mrgit) — 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: +It is best to install it globally in your system for an easier use later on: ```bash -npm install -g yarn mrgit +npm install -g yarn ``` **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): +Then clone the [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5): ```bash git clone https://github.com/ckeditor/ckeditor5.git @@ -46,129 +49,10 @@ cd ckeditor5 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 -yarn install -``` - -### 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 `mrgit`. 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 -mrgit sync -``` - -Expected result: - -```bash -(master 340feac) p@m /workspace/ckeditor5> tree -L 1 packages/ -packages/ -├── ckeditor5-autoformat -├── ckeditor5-basic-styles -├── ckeditor5-clipboard -... -└── ckeditor5-utils -``` - -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 -yarn install -``` - -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 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 -yarn run test --files=core -``` - -### Fetching changes - -Whenever you want to update all packages to their latest versions call: - ```bash -# To update the ckeditor5 repository itself: -git pull - -# To update pull changes to all the packages: -mrgit sync - -# To install missing dependencies: yarn install ``` -From time to time, if the list of dependencies in any of the packages changed, new package has been added to `ckeditor5` or you just want to make sure that you have the repository up to date, run the `reinstall` script: - -```bash -git pull -yarn run reinstall -``` - -The `reinstall` script first calls `yarn run clean` to remove `node_modules/` directories from all packages (including `ckeditor5`) and then `yarn run bootstrap` which is a shorthand for `mrgit sync && yarn install`. - -### Working with multiple repositories - -Mr. Git implements many useful commands, such as: - -* `mrgit exec 'command'` – executing a shell command in all repositories, -* `mrgit checkout ` – checking all repositories to given branch (or hash), -* `mrgit status` – displaying information about all repositories. - -Read more about those commands in [mrgit's documentation](https://github.com/cksource/mrgit). - -Mr. Git 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 `mrgit` for custom packages - -If you are developing custom packages or forked any of the official packages and want `mrgit` to work with it, change the dependencies configuration in [`mrgit.json`](https://github.com/ckeditor/ckeditor5/blob/master/mrgit.json). Note that `mrgit` is able to clone the package from any Git URL. Refer to [its documentation](https://github.com/cksource/mrgit) for more details. - ## Running tests In order to run tests you need to use the `test` and `manual` tasks. @@ -240,42 +124,6 @@ The stylesheet will be saved in the `build/content-styles` folder. To learn more, refer to the {@link builds/guides/integration/content-styles Content styles} guide. -## Bisecting through a multi-repository - -CKEditor 5 is a multi-repository project. It means that [`git bisect`](https://git-scm.com/docs/git-bisect) (which is super handy when tracking which commit introduced a bug) will not work out of the box. - -Fortunately, every commit made to any of the `master` branches of all CKEditor 5 subpackages will update this subpackage's hash in `mrgit.json` in the [`master-revisions`](https://github.com/ckeditor/ckeditor5/commits/master-revisions) branch. - -Thanks to that, `master-revisions` contains an ordered history of all changes which makes it possible to go back to any point in history: - -```bash -# Make sure to update this branch. -git co master-revisions -git pull - -# Check out 30 commits back. -git co master-revisions~30 - -# Check out subpackages to correct hashes. -mrgit co -``` - -Once you found the point in history which interests you, you can go straight to a commit in a subpackage and PR. For example: - -```bash -(detached:bisect/bad~1 cb2feef ?1) p@m /workspace/ckeditor5> git bisect good -ab5b5494e5eba7beb4a3bac4ea9c5e6d59a610f5 is the first bad commit -commit ab5b5494e5eba7beb4a3bac4ea9c5e6d59a610f5 -Author: Travis CI User -Date: Tue Apr 11 16:45:47 2017 +0000 - - Revision: https://github.com/ckeditor/ckeditor5-image/commit/02869eb4478a2f538006c128b30b9727617af665 - -:100644 100644 611526d5c4beae7046b0a08ec36843cbbe642175 35acdd8ba971d8127dd462a9c8c1162a54f00d58 M mgit.json -``` - -Leads to [`ckeditor/ckeditor5-image@02869eb`](https://github.com/ckeditor/ckeditor5-image/commit/02869eb) which leads to [ckeditor/ckeditor5-image#95](https://github.com/ckeditor/ckeditor5-image/pull/95). - ## Additional information for contributors ### SVG icons diff --git a/docs/framework/guides/contributing/testing-environment.md b/docs/framework/guides/contributing/testing-environment.md index 2b7263ee6a8..5a57571621a 100644 --- a/docs/framework/guides/contributing/testing-environment.md +++ b/docs/framework/guides/contributing/testing-environment.md @@ -11,7 +11,7 @@ Before reading this article we recommend getting familiar with the CKEditor 5 {@ The CKEditor 5 testing environment uses a popular setup with [Karma](https://karma-runner.github.io), [webpack](https://webpack.github.io/), [babel-loader](https://github.com/babel/babel-loader) and [Istanbul](https://github.com/gotwarlost/istanbul). We created some [npm scripts](https://docs.npmjs.com/cli/run-script) which glue all these pieces and special requirements for CKEditor together. -Each CKEditor 5 package has its own tests suite (see for example the [engine's tests](https://github.com/ckeditor/ckeditor5-engine/tree/master/tests)), however, the test runner is available in the [`ckeditor5`](https://github.com/ckeditor/ckeditor5) package which is the central development environment. The actual code of the test runner is implemented in the [`@ckeditor/ckeditor5-dev-tests`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-tests) package and can be easily reused outside of `ckeditor5`. +Each CKEditor 5 package has its own tests suite (see for example the [engine's tests](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests)), however, the test runner is available in the root of the [`ckeditor5`](https://github.com/ckeditor/ckeditor5) repository which is the central development environment. The actual code of the test runner is implemented in the [`@ckeditor/ckeditor5-dev-tests`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-tests) package and can be easily reused outside of `ckeditor5`. ## Running automated tests @@ -29,19 +29,19 @@ It accepts the following arguments that must be passed after the `--` option: ### Examples -Run all tests with the code coverage check of the [`ckeditor5-core`](https://github.com/ckeditor/ckeditor5-core) package: +Run all tests with the code coverage check of the [`ckeditor5-core`](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) package: ```bash 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): +Run and watch the [engine's `view` namespace tests](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests/view) and all the tests in [`ckeditor5-typing`](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-typing/tests): ```bash 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: +Run the `bold*.js` tests in the [`ckeditor5-basic-styles`](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-basic-styles/tests) package: ```bash yarn run test -cw --files=basic-styles/bold*.js @@ -54,7 +54,7 @@ In order to start the manual tests server, use the `yarn run manual` task. The task accepts the following options: * `--source-map` (alias `-s`) – Whether to generate useful source maps for the code. -* `--files` – Specifies test files to run. Accepts a package name or a glob. For example `--files=ckeditor5` will run tests from the main repository. Read more about the [rules for converting the `--files` option to a glob pattern](https://github.com/ckeditor/ckeditor5-dev/tree/master/packages/ckeditor5-dev-tests#rules-for-converting---files-option-to-glob-pattern). +* `--files` – Specifies test files to run. Accepts a package name or a glob. For example `--files=ckeditor5` will only run tests from the CKEditor 5 main package. Read more about the [rules for converting the `--files` option to a glob pattern](https://github.com/ckeditor/ckeditor5-dev/tree/master/packages/ckeditor5-dev-tests#rules-for-converting---files-option-to-glob-pattern). * `--additionalLanguages="ar,pl,..."` – Specifies extra languages to the [CKEditor 5 webpack plugin](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin). Check out the {@link features/ui-language UI language guide} to learn more. * `--debug` (alias `-d`) – Allows specifying custom debug flags. For example, the `--debug engine` option uncomments the `// @if CK_DEBUG_ENGINE //` lines in the code. Note that by default `--debug` is set to `true` even if you did not specify it. This enables the base set of debug logs (`// @if CK_DEBUG //`) which should always be enabled in the testing environment. You can completely turn off the debug mode by setting the `--debug false` option. diff --git a/docs/framework/guides/overview.md b/docs/framework/guides/overview.md index 3ab584c6233..500daae4b34 100644 --- a/docs/framework/guides/overview.md +++ b/docs/framework/guides/overview.md @@ -37,9 +37,9 @@ The framework was designed to be a highly flexible and universal platform for cr ## Framework structure -The framework is made of several [npm packages](https://npmjs.com). Every package is developed in its own repository, making CKEditor 5 a multi-repository project. The main repository that glues all of them and contains the CKEditor 5 development environment is https://github.com/ckeditor/ckeditor5. +The framework is made of several [npm packages](https://npmjs.com). Each package is available in the `/packages` directory of the https://github.com/ckeditor/ckeditor5 repository. -A complete list of official packages that constitute the framework is available in the [main repository's README](https://github.com/ckeditor/ckeditor5#packages). +A complete list of official packages that constitute the framework is available in the [CKEditor 5 repository's README](https://github.com/ckeditor/ckeditor5#packages). There are a few groups of packages: diff --git a/packages/ckeditor5-select-all/docs/features/select-all.md b/packages/ckeditor5-select-all/docs/features/select-all.md index 4368d5ed3c4..1de2346c648 100644 --- a/packages/ckeditor5-select-all/docs/features/select-all.md +++ b/packages/ckeditor5-select-all/docs/features/select-all.md @@ -9,7 +9,7 @@ The {@link module:select-all/selectall~SelectAll} feature allows selecting the e ## Demo -Press Ctrl/⌘+A or use the toolbar button to select the entire content of the editor. Note that when editing an image caption, the selection will only expand to the boundaries of the caption. +Press Ctrl/⌘+A or use the toolbar button to select the entire content of the editor. Note that when editing an {@link features/image#image-captions image caption}, the selection will only expand to the boundaries of the caption. {@snippet features/select-all} diff --git a/packages/ckeditor5-table/lang/contexts.json b/packages/ckeditor5-table/lang/contexts.json index e7df81d68eb..fc742f98077 100644 --- a/packages/ckeditor5-table/lang/contexts.json +++ b/packages/ckeditor5-table/lang/contexts.json @@ -4,13 +4,13 @@ "Insert column left": "Label for the insert table column to the left of the current one button.", "Insert column right": "Label for the insert table column to the right of the current one button.", "Delete column": "Label for the delete table column button.", - "Select column": "Label for the select table entire column button.", + "Select column": "Label for the select the entire table column button.", "Column": "Label for the table column dropdown button.", "Header row": "Label for the set/unset table header row button.", "Insert row below": "Label for the insert row below button.", "Insert row above": "Label for the insert row above button.", "Delete row": "Label for the delete table row button.", - "Select row": "Label for the select table entire row button.", + "Select row": "Label for the select the entire table row button.", "Row": "Label for the table row dropdown button.", "Merge cell up": "Label for the merge table cell up button.", "Merge cell right": "Label for the merge table cell right button.", diff --git a/packages/ckeditor5-table/src/commands/mergecellcommand.js b/packages/ckeditor5-table/src/commands/mergecellcommand.js index 2e191d4ab40..31f518dd7fb 100644 --- a/packages/ckeditor5-table/src/commands/mergecellcommand.js +++ b/packages/ckeditor5-table/src/commands/mergecellcommand.js @@ -264,7 +264,7 @@ function removeEmptyRow( removedTableCellRow, writer ) { } // Merges two table cells. It will ensure that after merging cells with an empty paragraph, the resulting table cell will only have one -// paragraph. If one of the merged table cell is empty, the merged table cell will have the contents of the non-empty table cell. +// paragraph. If one of the merged table cells is empty, the merged table cell will have the contents of the non-empty table cell. // If both are empty, the merged table cell will have only one empty paragraph. // // @param {module:engine/model/element~Element} cellToRemove diff --git a/packages/ckeditor5-table/src/commands/mergecellscommand.js b/packages/ckeditor5-table/src/commands/mergecellscommand.js index 74eb728295f..c42982acff3 100644 --- a/packages/ckeditor5-table/src/commands/mergecellscommand.js +++ b/packages/ckeditor5-table/src/commands/mergecellscommand.js @@ -16,7 +16,7 @@ import { getColumnIndexes, getRowIndexes, getSelectedTableCells } from '../utils /** * The merge cells command. * - * The command is registered by the {@link module:table/tableediting~TableEditing} as `'mergeTableCells'` editor command. + * The command is registered by {@link module:table/tableediting~TableEditing} as the `'mergeTableCells'` editor command. * * For example, to merge selected table cells: * @@ -44,7 +44,7 @@ export default class MergeCellsCommand extends Command { model.change( writer => { const selectedTableCells = getSelectedTableCells( model.document.selection ); - // All cells will be merge into the first one. + // All cells will be merged into the first one. const firstTableCell = selectedTableCells.shift(); // Set the selection in cell that other cells are being merged to prevent model-selection-range-intersects error in undo. @@ -68,7 +68,7 @@ export default class MergeCellsCommand extends Command { } } -// Properly removes the empty row from a table. Updates the `rowspan` attribute of cells that overlap the removed row. +// Properly removes an empty row from a table. Updates the `rowspan` attribute of cells that overlap the removed row. // // @param {module:engine/model/element~Element} row // @param {module:engine/model/writer~Writer} writer @@ -91,8 +91,8 @@ function removeRowIfEmpty( row, writer ) { writer.remove( row ); } -// Merges two table cells - will ensure that after merging cells with empty paragraphs the result table cell will only have one paragraph. -// If one of the merged table cells is empty, the merged table cell will have contents of the non-empty table cell. +// Merges two table cells. It will ensure that after merging cells with empty paragraphs the resulting table cell will only have one +// paragraph. If one of the merged table cells is empty, the merged table cell will have contents of the non-empty table cell. // If both are empty, the merged table cell will have only one empty paragraph. // // @param {module:engine/model/element~Element} cellBeingMerged @@ -119,7 +119,7 @@ function isEmpty( tableCell ) { return tableCell.childCount == 1 && tableCell.getChild( 0 ).is( 'paragraph' ) && tableCell.getChild( 0 ).isEmpty; } -// Checks if the selection contains mergeable cells. +// Checks if the selection contains cells that can be merged. // // In a table below: // @@ -138,8 +138,8 @@ function isEmpty( tableCell ) { // - c, d, f (cell d spans over a cell in the row below) // // While an invalid selection would be: -// - a, c (cell "b" not selected creates a gap) -// - f, g, h (cell "d" spans over a cell from row of "f" cell - thus creates a gap) +// - a, c (the unselected cell "b" creates a gap) +// - f, g, h (cell "d" spans over a cell from the row of "f" cell - thus creates a gap) // // @param {module:engine/model/selection~Selection} selection // @param {module:table/tableUtils~TableUtils} tableUtils @@ -187,7 +187,7 @@ function canMergeCells( selection, tableUtils ) { return areaOfValidSelection == areaOfSelectedCells; } -// Calculates the area of a maximum rectangle that can span over provided row & column indexes. +// Calculates the area of a maximum rectangle that can span over the provided row & column indexes. // // @param {Array.} rows // @param {Array.} columns @@ -204,7 +204,7 @@ function getBiggestRectangleArea( rows, columns ) { return ( lastRow - firstRow + 1 ) * ( lastColumn - firstColumn + 1 ); } -// Checks if the selection does not mix header (column or row) with other cells. +// Checks if the selection does not mix a header (column or row) with other cells. // // For instance, in the table below valid selections consist of cells with the same letter only. // So, a-a (same heading row and column) or d-d (body cells) are valid while c-d or a-b are not. diff --git a/packages/ckeditor5-table/src/tablenavigation.js b/packages/ckeditor5-table/src/tablenavigation.js index 6774c7d255f..44ec32dc1cf 100644 --- a/packages/ckeditor5-table/src/tablenavigation.js +++ b/packages/ckeditor5-table/src/tablenavigation.js @@ -86,7 +86,7 @@ export default class TableNavigation extends Plugin { /** * Returns a handler for {@link module:engine/view/document~Document#event:keydown keydown} events for the Tab key executed - * inside table cell. + * inside table cells. * * @private * @param {Boolean} isForward Whether this handler will move the selection to the next or the previous cell. @@ -180,7 +180,7 @@ export default class TableNavigation extends Plugin { } /** - * Handles arrow keys to move the selection around a table. + * Handles arrow keys to move the selection around the table. * * @private * @param {'left'|'up'|'right'|'down'} direction The direction of the arrow key. @@ -276,7 +276,7 @@ export default class TableNavigation extends Plugin { } /** - * Returns true if the selection is at the boundary of a table cell according to the navigation direction. + * Returns `true` if the selection is at the boundary of a table cell according to the navigation direction. * * @private * @param {module:engine/model/selection~Selection} selection The current selection. @@ -305,12 +305,12 @@ export default class TableNavigation extends Plugin { /** * Checks if there is an {@link module:engine/model/element~Element element} next to the current - * {@link module:engine/model/selection~Selection model selection} marked in + * {@link module:engine/model/selection~Selection model selection} marked in the * {@link module:engine/model/schema~Schema schema} as an `object`. * * @private * @param {module:engine/model/selection~Selection} modelSelection The selection. - * @param {Boolean} isForward Direction of checking. + * @param {Boolean} isForward The direction of checking. * @returns {Boolean} */ _isObjectElementNextToSelection( modelSelection, isForward ) { @@ -326,12 +326,12 @@ export default class TableNavigation extends Plugin { /** * Truncates the range so that it spans from the last selection position - * to the last allowed $text position (mirrored if isForward is false). + * to the last allowed `$text` position (mirrored if `isForward` is false). * - * Returns `null` if resulting range can't contain $text element (according to schema). + * Returns `null` if, according to the schema, the resulting range cannot contain a `$text` element. * * @private - * @param {module:engine/model/range~Range} range Current table cell content range. + * @param {module:engine/model/range~Range} range The current table cell content range. * @param {module:engine/model/selection~Selection} selection The current selection. * @param {Boolean} isForward The expected navigation direction. * @returns {module:engine/model/range~Range|null} @@ -361,13 +361,13 @@ export default class TableNavigation extends Plugin { } /** - * Basing on provided range, finds first/last (depending on `direction`) position inside the range + * Basing on the provided range, finds the first or last (depending on `direction`) position inside the range * that can contain `$text` (according to schema) and is visible in the view. * * @private - * @param {module:engine/model/range~Range} range The range to find position in. + * @param {module:engine/model/range~Range} range The range to find the position in. * @param {'forward'|'backward'} direction Search direction. - * @returns {module:engine/model/position~Position} Nearest selection range. + * @returns {module:engine/model/position~Position} The nearest selection range. */ _getNearestVisibleTextPosition( range, direction ) { const schema = this.editor.model.schema; @@ -385,11 +385,11 @@ export default class TableNavigation extends Plugin { } /** - * Checks if the DOM range corresponding to provided model range renders as a single line by analyzing DOMRects + * Checks if the DOM range corresponding to the provided model range renders as a single line by analyzing DOMRects * (verifying if they visually wrap content to the next line). * * @private - * @param {module:engine/model/range~Range} modelRange Current table cell content range. + * @param {module:engine/model/range~Range} modelRange The current table cell content range. * @param {Boolean} isForward The expected navigation direction. * @returns {Boolean} */ @@ -515,7 +515,7 @@ export default class TableNavigation extends Plugin { } } -// Returns 'true' if provided key code represents one of the arrow keys. +// Returns `true` if the provided key code represents one of the arrow keys. // // @private // @param {Number} keyCode @@ -527,7 +527,7 @@ function isArrowKeyCode( keyCode ) { keyCode == keyCodes.arrowdown; } -// Returns direction name from `keyCode`. +// Returns the direction name from `keyCode`. // // @private // @param {Number} keyCode diff --git a/packages/ckeditor5-table/src/utils.js b/packages/ckeditor5-table/src/utils.js index f5536c11166..2fefc1e2d7f 100644 --- a/packages/ckeditor5-table/src/utils.js +++ b/packages/ckeditor5-table/src/utils.js @@ -139,7 +139,7 @@ export function getSelectionAffectedTableCells( selection ) { } /** - * Returns an object with `first` and `last` row index contained in the given `tableCells`. + * Returns an object with the `first` and `last` row index contained in the given `tableCells`. * * const selectedTableCells = getSelectedTableCells( editor.model.document.selection ); * @@ -148,7 +148,7 @@ export function getSelectionAffectedTableCells( selection ) { * console.log( `Selected rows: ${ first } to ${ last }` ); * * @param {Array.} tableCells - * @returns {Object} Returns an object with `first` and `last` table row indexes. + * @returns {Object} Returns an object with the `first` and `last` table row indexes. */ export function getRowIndexes( tableCells ) { const indexes = tableCells.map( cell => cell.parent.index ); @@ -157,7 +157,7 @@ export function getRowIndexes( tableCells ) { } /** - * Returns an object with `first` and `last` column index contained in the given `tableCells`. + * Returns an object with the `first` and `last` column index contained in the given `tableCells`. * * const selectedTableCells = getSelectedTableCells( editor.model.document.selection ); * @@ -166,7 +166,7 @@ export function getRowIndexes( tableCells ) { * console.log( `Selected columns: ${ first } to ${ last }` ); * * @param {Array.} tableCells - * @returns {Object} Returns an object with `first` and `last` table column indexes. + * @returns {Object} Returns an object with the `first` and `last` table column indexes. */ export function getColumnIndexes( tableCells ) { const table = findAncestor( 'table', tableCells[ 0 ] );