Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
235 lines (162 loc) · 6.39 KB

CONTRIBUTING.md

File metadata and controls

235 lines (162 loc) · 6.39 KB

Contributing

Jodit is an open-source project, and we greatly appreciate your contributions. You can contribute by fixing bugs, reporting them, or translating the editor interface.

TL;DR

git clone git@github.com:xdan/jodit.git
cd jodit
nvm use
npm ci

To work you will need to install make.

make start

Make code changes and add automated tests in the test/tests/ folder. Run:

make lint && make test

Fix any issues and commit your changes:

git checkout -b i/GITHUB-ISSUE-NUMBER
git add . && git commit -m "Fixed issue smt"
git push

Create a pull request in your repository on the GitHub interface.

Requirement

To work on Jodit, you need the make utility.

Getting started

Clone the repository and install the dependencies.

git clone git@github.com:xdan/jodit.git
cd jodit
nvm use
npm ci
make start

The make start command starts the development server in debug mode, and the default page will open automatically. The command can be parameterized, for example, to run the build in es2018 mode:

make start es=es2018

You can find other options in the Makefile.

Fixing Issues and Adding Features

Before you start, here are some important points to keep in mind:

  • We expect contributions to adhere to high-quality code standards, including coding style and tests. Neglecting these points may slow down the acceptance of your contribution or even lead to rejection.
  • There is no guarantee that your contribution will be included in the project code. However, pull requests make it easy for you to keep your changes for personal use or for others who may find them useful.
  • If you need help creating a patch or implementing a feature, please submit a ticket to us on the issue tracker.

Code style

To ensure that your code matches the project's general style, you can use Prettier:

npx prettier ./src/%YOUR_PATCHED_FILE_PATH% --write

More information about the code style is provided in the guide. It is also important to run the following command without any errors before creating a pull request:

make lint

We follow simple code formatting rules that your IDE or editor can help you with.

Build

Build min files:

make build

Build without any plugins:

make build es=es2021 uglify=true excludePlugins="about,source,bold,image,xpath,stat,class-span,color,clean-html,file,focus,enter,backspace,media,preview,pint,redo-undo,resize-cells,search,spellcheck,table"

Build without some languages:

make build es=es2021 uglify=true excludeLanguages="ru,ar,cs_cz,de,es,fa,fi,fr,he,hu,id,it,ja,ko,nl,pl,pt_br,ru,tr,zh_cn,zh_tw"

Bundle Size Analysis (Statoscope)

To analyze the bundle and generate an interactive report:

make statoscope

This builds the es2021 fat bundle with Statoscope.

If statoscope/reference.json already exists (committed baseline), the new stats go to reference.next.json for comparison. If not — it creates the initial reference.json.

# Compare against baseline
make statoscope
make statoscope-validate
  • statoscope/reference.json — baseline (committed to git, updated on make newversion)
  • build/statoscope-report.html — interactive report (open in browser)

Validation rules are configured in statoscope.config.js. In CI, Statoscope runs automatically on every push/PR and posts comparison results.

Tests

Before making any functional changes or fixing a bug, you need to create tests for them. We follow the TDD (Test-Driven Development) methodology, where we write automated tests first and then implement the functionality. Maintaining a comprehensive test suite is crucial for our editor. To run all tests, use the following command:

make test

or

npm test

In several browsers:

make test browsers=Chrome,Firefox

This command builds the project and runs the automated tests. If you only want to run the tests on an existing build, you can simply use:

make test-only-run

or

make test-only-run browsers=Chrome

If you need to run a specific test, you can use the only method:

describe.only('Test', () => {
	it.only('Test', () => {});
});

To see the test results, you can run the tests in watch mode:

make test-only-run browsers=Chrome singleRun=false

For checking tests in browser, open URL:

http://localhost:2000/test/test.html

Creating a Pull Request

GitHub provides excellent documentation about pull requests. If you are unsure about the process, that is the right place to start

Assuming that you would like to propose some changes, follow these steps to create a pull request:

  • Make sure to open a ticket in https://github.com/xdan/jodit describing the issue, feature, or problem that you want to address in your pull request. This step can be skipped for obvious and trivial changes (e.g., typos, documentation fixes).
  • Go to GitHub and fork the repository. The forked repository will appear in your GitHub account as https://github.com/YOUR-USERNAME/jodit.
  • Open your terminal and navigate to the package's folder in your development environment:
$ cd path/to/jodit
  • Create a new branch for your code. We use the i/GITHUB-ISSUE-NUMBER convention for branch names:
$ git checkout -b i/GITHUB-ISSUE-NUMBER
  • Make the necessary changes, ensuring that you adhere to the code-style guidelines and remember to include tests for your changes.
  • Commit your changes using the following command:
$ git commit -m "Fixed issue smt."
  • Now it's time to make your changes public. First, you need to let git know about the fork you created by adding the remote repository:
$ git remote add my-fork https://github.com/YOUR-USERNAME/jodit
  • Push your changes to your forked repository:
$ git push my-fork i/GITHUB-ISSUE-NUMBER
  • Go to your forked repository on GitHub. Use the pull request button and follow the instructions provided.
⚡