Contribute to this guide

guideContributing

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 and 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.
  • Having a 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 development environment guide.

# Code style

Read more in the code style, naming and file naming 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 — 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 testing environment.

# Creating a pull request

GitHub provides an excellent documentation about 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 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.

  2. Make sure your development environment is ready.

  3. Go to GitHub and fork the repository (ckeditor5-link in this particular case). The forked repository will appear in your GitHub account as https://github.com/YOUR-USERNAME/ckeditor5-link.

  4. Open your terminal, then go to the package (“repository”) folder in your development environment:

    $ cd path/to/ckeditor5/packages/ckeditor5-link
    
  5. Start a new branch for your code. We use the t/GITHUB-ISSUE-NUMBER convention for branch names:

    $ git checkout -b t/GITHUB-ISSUE-NUMBER
    
  6. Make the changes. Stick to the code-style guidelines and remember about tests and 100% code coverage!

  7. Commit your changes:

    $ git commit -m "Squashed a nasty bug in the link editing."
    
  8. 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:

    $ git remote add my-fork https://github.com/YOUR-USERNAME/ckeditor5-link
    
  9. Push your changes to your forked repository:

    $ git push my-fork t/GITHUB-ISSUE-NUMBER
    
  10. Go to your forked repository on GitHub. Use the pull request button and follow the instructions. Make sure to include a merge commit message text matches the convention

  11. 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 — 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) and that tests pass. Test your changes!

If want your changes to be permanent in your development environment, make sure your mrgit.json file 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.

We use the Transifex service for translations at the following address: 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 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/.