Sfoglia il codice sorgente

Merge pull request #6524 from ckeditor/monorepo-docs

Docs: Documentation changes for monorepo migration. Closes #6523.
Piotrek Koszuliński 5 anni fa
parent
commit
4f871affda

+ 2 - 2
README.md

@@ -107,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.
 

+ 0 - 2
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

+ 6 - 1
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:
 

+ 12 - 12
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.
 </info-box>
 
-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:
+<info-box>
+	[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).
+</info-box>
+
+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!
 
-<info-box>
-	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.
-</info-box>
-
 ## Translating
 
 CKEditor 5 is a project with global impact, so contributing translations is both an easy and powerful way to help.

+ 13 - 165
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).
 
+<info-box info>
+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.
+</info-box>
+
 ## 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) &mdash; A multi-repo management tool,
-* [Yarn](https://yarnpkg.com/) &mdash; 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 <branch>` – 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 <travis@example.org>
-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

File diff suppressed because it is too large
+ 5 - 5
docs/framework/guides/contributing/testing-environment.md


+ 2 - 2
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: