Преглед на файлове

Merge branch 'master' into t/416

Aleksander Nowodzinski преди 7 години
родител
ревизия
70b9c56d84

+ 1 - 66
CONTRIBUTING.md

@@ -1,69 +1,4 @@
 Contributing
 ========================================
 
-## Fixing issues and coding features
-
-Things to keep in mind:
-
-* We expect contributions to follow the high-quality code standards that we follow, including [coding style](#code-style) and [tests](#tests). Lack of attention to this point may either make it slow to adopt a contribution or even force us to reject it altogether.
-* There is no guarantee that your contribution will be incorporated in the main code. Still, pull requests make it easy for you to keep them for your own use or for others which may be interested in them.
-* If you plan to start working on a bigger task, it might be worth asking the core team (beforehand) whether a specific feature or solution to an issue will be accepted.
-* If you need any assistance when creating a patch or implementing a feature, ping us under a ticket or on [Twitter](https://twitter.com/ckeditor).
-* Having a CLA is essential to have your contributions accepted ([see bellow](#contributor-license-agreement-cla)).
-
-### Setting up the development environment
-
-To learn how to set up the project and run tests see the [development environment](https://github.com/ckeditor/ckeditor5/wiki/Development-environment) guide.
-
-### Code style
-
-Read more in [code style](https://github.com/ckeditor/ckeditor5-design/wiki/Code-Style), [naming](https://github.com/ckeditor/ckeditor5-design/wiki/Code-Style-Naming-Guidelines) and [file naming](https://github.com/ckeditor/ckeditor5-design/wiki/File-Names) guidelines.
-
-Every package repository installs git hooks which automatically lints and check the code for code style on commit. However, not every code style issue can be discovered this way, so please do not rely on tools too much :).
-
-### Tests
-
-We maintain a 100% of code coverage (including code branches) and pull requests with missing tests will not be accepted. However, keep in mind that 100% is not everything – every *change* must be tested. This means that if you are fixing a bug and your patch did not change the code coverage, the change itself needs a test anyway.
-
-Besides automated tests, you may be asked to create a manual test for the issue. Such manual tests let us quickly validate that the issue was really fixed and are later used during a testing phase (before a release) to make sure no regressions were created.
-
-Read more about our [testing environment](https://github.com/ckeditor/ckeditor5/wiki/Testing-environment).
-
-### Making a pull request
-
-GitHub provides an [extensive documentation about pull requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/), so we will skip that.
-
-The only additional things you need to remember is to:
-
-* Fork the repository (CKEditor 5 is a multi-repo project) in which you want to propose a pull request.
-* Start a branch for your code (we use `t/<ticket name>` convention for branch names).
-* Your pull request should be minimal – i.e. change only things described in the ticket. Do not squeeze unrelated changes into your pull request.
-* 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.
-
-## Translating
-
-Being this a project with global impact, contributing translations is both an easy and powerful way to help.
-
-We use the Transifex service for translations at the following address: [https://www.transifex.com/ckeditor/ckeditor5/dashboard/](https://www.transifex.com/ckeditor/ckeditor5/dashboard/).
-
-Here as well, having a CLA in place is a requirement to become an official translator (see bellow).
-
-## Reporting issues / requesting features
-
-[Each repository](https://github.com/ckeditor/ckeditor5#packages) independently handles its issues. However, it's recommended to report issues in [the main repository](https://github.com/ckeditor/ckeditor5/issues) unless you know to which specific repository the issue belongs.
-
-Things to keep in mind:
-
-* Search for existing issues before starting a new one. This helps our team to have the backlog in order.
-* Be concise and informative, making it easy for our team to understand the problem.
-* Do not use the issues pages for asking for help.
-* Feel free to jump into discussions around issues, exposing your opinion.
-
-The issues pages can be used for feature requests.
-
-## Contributor License Agreement (CLA)
-
-To accept contributions sent to us in form of code, documentation or translations, a Contributor License Agreement (CLA) must be in place in order to clarify the intellectual property license granted with them. This license is for your protection as a contributor as well as the protection of us and our users; it does not change your rights to use your own contributions for any other purpose.
-
-To sign the CLA and to have more information, please follow this link: [http://cla.ckeditor.com/](http://cla.ckeditor.com/).
+See the [official contributors' guide to CKEditor 5](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/contributing.html) to learn more.

+ 2 - 0
README.md

@@ -122,6 +122,8 @@ CKEditor 5 is a modular, multi-package, multi-repository project. It consists of
 
 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.
 
+See the [official contributors' guide](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/contributing.html) to learn how to contribute your code to the project.
+
 ### Reporting issues and feature requests
 
 Each repository handles its issues independently. However, it is recommended to report issues in [this repository](https://github.com/ckeditor/ckeditor5/issues) unless you know to which specific repository the issue belongs.

+ 6 - 14
docs/builds/guides/frameworks/angular.md

@@ -32,14 +32,6 @@ Assuming that you picked [`@ckeditor/ckeditor5-build-classic`](https://www.npmjs
 npm install --save-dev @ckeditor/ckeditor5-build-classic
 ```
 
-**Note:** You may need to allow external JavaScript in your project's `tsconfig.json` for the builds to work properly:
-
-```json
-"compilerOptions": {
-	"allowJs": true
-}
-```
-
 Now, add `CKEditorModule` to your application module imports:
 
 ```ts
@@ -72,10 +64,10 @@ export class MyComponent {
 Finally, use the `<ckeditor>` tag in the template to run the rich text editor:
 
 ```html
-<ckeditor [editor]="Editor" data="<p>Hello world!</p>"></ckeditor>
+<ckeditor [editor]="Editor" data="<p>Hello, world!</p>"></ckeditor>
 ```
 
-Rebuild your application and CKEditor 5 should greet you with "Hello world!".
+Rebuild your application and CKEditor 5 should greet you with "Hello, world!".
 
 ### Note: Using the Document editor build
 
@@ -102,7 +94,7 @@ export class MyComponent {
 And then, in the template:
 
 ```html
-<ckeditor [editor]="Editor" data="<p>Hello world!</p>" (ready)="onReady($event)"></ckeditor>
+<ckeditor [editor]="Editor" data="<p>Hello, world!</p>" (ready)="onReady($event)"></ckeditor>
 ```
 
 ## Integration with `ngModel`
@@ -117,7 +109,7 @@ The component implements the [`ControlValueAccessor`](https://angular.io/api/for
 	} )
 	export class MyComponent {
 		public model = {
-			editorData: '<p>Hello world!</p>'
+			editorData: '<p>Hello, world!</p>'
 		};
 		...
 	}
@@ -154,7 +146,7 @@ The {@link module:core/editor/editorconfig~EditorConfig configuration} of the ed
 The initial data of the editor. It can be a static value:
 
 ```html
-<ckeditor data="<p>Hello world!</p>" ...></ckeditor>
+<ckeditor data="<p>Hello, world!</p>" ...></ckeditor>
 ```
 
 or a shared parent component's property
@@ -164,7 +156,7 @@ or a shared parent component's property
 	...
 } )
 export class MyComponent {
-	public editorData = '<p>Hello world!</p>';
+	public editorData = '<p>Hello, world!</p>';
 	...
 }
 ```

+ 12 - 2
docs/builds/guides/frameworks/react.md

@@ -10,10 +10,20 @@ order: 30
 
 CKEditor 5 consists of {@link builds/guides/overview ready-to-use editor builds} and {@link framework/guides/overview CKEditor 5 Framework} upon which the builds are based.
 
-The easiest way to use CKEditor 5 in your React application is by choosing one of the {@link builds/guides/overview#available-builds rich text editor builds}. Additionally, it is also possible to integrate [CKEditor 5 built from source](#integrating-ckeditor-5-from-source) into your application .
+The easiest way to use CKEditor 5 in your React application is by choosing one of the {@link builds/guides/overview#available-builds rich text editor builds}. Additionally, it is also possible to integrate [CKEditor 5 built from source](#integrating-ckeditor-5-from-source) into your application.
 
 ## Quick start
 
+<info-box>
+	### Compatibility with `create-react-app@2`
+
+	The latest version of `create-react-app` (2.x) does not work with CKEditor 5 Builds due to a [bug (most likely in Babel)](https://github.com/facebook/create-react-app/issues/5387).
+
+	If you want to use CKEditor 5 with an application created via `create-react-app@2` you will need to [eject the configuration even in the development mode](https://github.com/facebook/create-react-app/issues/5387#issuecomment-429255695).
+
+	Until the above issue is resolved, in this guide we will use `create-react-app@1` which does not require ejecting the configuration when testing your application in the development mode. You will have to, however, eject it anyway to [build your app for production](#note-building-for-production).
+</info-box>
+
 Install the [CKEditor 5 rich text editor component for React](https://www.npmjs.com/package/@ckeditor/ckeditor5-react) and the build of your choice.
 
 Assuming that you picked [`@ckeditor/ckeditor5-build-classic`](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-classic):
@@ -141,7 +151,7 @@ This guide assumes that you are using [Create React App CLI](https://github.com/
 Install React CLI:
 
 ```bash
-npm install -g create-react-app
+npm install -g create-react-app@1
 ```
 
 Create your project using the CLI and go to the project's directory:

+ 7 - 0
docs/builds/guides/support/reporting-issues.md

@@ -26,4 +26,11 @@ All issues should be reported in the [CKEditor 5 repositories](https://github.co
 
 Issues related to builds are usually caused by issues in the CKEditor 5 Framework components and plugins included in the build. You may report issues directly into the repositories that you think are related to them (like plugins) but, if you are unsure, the [`ckeditor5` issues page](https://github.com/ckeditor/ckeditor5/issues) should be used as the fallback place for any issue. The CKEditor 5 team will then move the issue to the right place or give you further instructions, if necessary.
 
+Things to keep in mind:
+
+* Search for existing issues before starting a new one. This helps our team to have the backlog in order.
+* Be concise and informative, making it easy for our team to understand the problem.
+* Do not use the issues pages for asking for help. The project has other {@link framework/guides/support/getting-support communication channels} for that purpose.
+* Feel free to jump into discussions around issues, exposing your opinion!
+
 Issues with third-party plugins should be reported directly to their developers.

+ 8 - 2
docs/framework/guides/architecture/ui-library.md

@@ -387,12 +387,18 @@ const items = new Collection();
 
 items.add( {
 	type: 'button',
-	model: new Model( { label: 'Foo' } )
+	model: new Model( {
+		withText: true,
+		label: 'Foo'
+	} )
 } );
 
 items.add( {
 	type: 'button',
-	model: new Model( { label: 'Bar' } )
+	model: new Model( {
+		withText: true,
+		label: 'Bar'
+	} )
 } );
 
 // Create a dropdown with a list inside the panel.

+ 109 - 0
docs/framework/guides/contributing/contributing.md

@@ -0,0 +1,109 @@
+---
+category: framework-contributing
+order: 10
+---
+
+# Contributing
+
+CKEditor 5 is an Open Source project and we will be most thankful for your contributions. You can help us by fixing issues, reporting them or translating the editor interface. Community effort and engagement is what has been driving the development of our WYSIWYG editor projects since 2003!
+
+## Fixing issues and coding features
+
+Before you start, here are some things to keep in mind:
+
+* We expect contributions to follow the high-quality code standards that we follow, including [coding style](#code-style) and [tests](#tests). Lack of attention to this point may either make it slow to adopt a contribution or even force us to reject it altogether.
+* There is no guarantee that your contribution will be incorporated into the project code. Still, pull requests make it easy for you to keep them for your own use or for others who may be interested in them.
+* If you plan to start working on a bigger task, it might be worth asking the core team (beforehand) whether a specific feature or a solution to an issue will be accepted.
+* If you need any assistance when creating a patch or implementing a feature, ping us under the ticket or on [Gitter](https://gitter.im/ckeditor/ckeditor5).
+* [Having a CLA](#contributor-license-agreement-cla) is essential to have your contributions accepted.
+
+### Setting up the development environment
+
+To learn how to set up the project and run tests see the {@link framework/guides/contributing/development-environment development environment} guide.
+
+### Code style
+
+Read more in the [code style](https://github.com/ckeditor/ckeditor5-design/wiki/Code-Style), [naming](https://github.com/ckeditor/ckeditor5-design/wiki/Code-Style-Naming-Guidelines) and [file naming](https://github.com/ckeditor/ckeditor5-design/wiki/File-Names) guidelines.
+
+Every package repository installs Git hooks that automatically lint and check the code for code style on commit. However, not every code style issue can be discovered this way, so please do not rely on tools too much :).
+
+### Tests
+
+We maintain a **100% code coverage** (including code branches) and pull requests with missing tests will not be accepted. However, keep in mind that 100% is not everything &mdash; every *change* must be tested. This means that if you are fixing a bug and your patch did not change the code coverage, the change itself needs a test anyway.
+
+Besides automated tests, you may be asked to create a manual test for the issue. Such manual tests let us quickly validate that the issue was really fixed and are later used during the testing phase (before a release) to make sure no regressions were created.
+
+Read more about our {@link framework/guides/contributing/testing-environment testing environment}.
+
+### Creating a pull request
+
+<info-box>
+	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:
+
+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 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. Open your terminal, then go to the package ("repository") folder in your development environment:
+
+	```shell
+	$ cd path/to/ckeditor5/packages/ckeditor5-link
+	```
+
+1. Start a new branch for your code. We use the `t/GITHUB-ISSUE-NUMBER` convention for branch names:
+
+	```shell
+	$ git checkout -b t/GITHUB-ISSUE-NUMBER
+	```
+
+1. Make the changes. Stick to the [code-style guidelines](#code-style) and remember about [tests and 100% code coverage](#tests)!
+1. Commit your changes:
+
+	```shell
+	$ git commit -m "Squashed a nasty bug in the link editing."
+	```
+
+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
+	```
+
+1. Push your changes to your forked repository:
+
+	```shell
+	$ git push my-fork t/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}
+1. **Let us know about your pull request!** The best way is to comment under the original issue.
+
+Some additional things you should keep in mind:
+
+* Your pull request should be minimal &mdash; i.e. change only things described in the ticket. Do not squeeze unrelated changes into your pull request.
+* 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 `mgit.json` file {@link framework/guides/contributing/development-environment#using-mgit-for-custom-packages points to your forked version of the repository} so next time you execute `mgit update` 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.
+
+We use the Transifex service for translations at the following address: [https://www.transifex.com/ckeditor/ckeditor5/dashboard/](https://www.transifex.com/ckeditor/ckeditor5/dashboard/).
+
+Here as well, having a CLA in place is a requirement to become an official translator (see below).
+
+## Reporting issues and requesting features
+
+Read the {@link framework/guides/support/reporting-issues reporting issues} guide to learn more.
+
+## Contributor License Agreement (CLA)
+
+To accept contributions sent to us in form of code, documentation or translations, a Contributor License Agreement (CLA) must be in place in order to clarify the intellectual property license granted with them. This license is for your protection as a contributor as well as the protection of us and our users; it does not change your rights to use your own contributions for any other purpose.
+
+To sign the CLA and to get more information, please follow this link: [https://cla.ckeditor.com/](https://cla.ckeditor.com/).