Skip to content

Latest commit

 

History

History
90 lines (54 loc) · 5.04 KB

README_DEVELOPERS.md

File metadata and controls

90 lines (54 loc) · 5.04 KB
Raw

README for Developers

We use the Fork-and-Branch workflow. Start with forking the repository, then create a branch to which you commit modifications.

Don't clone the main repository!

Create a pull request to one of the main branches (e.g. 16_2) when you are ready to submit your changes. Each pull request should pass all automatic checks and at least one member of the DevExtreme team should review it.

Make sure that you properly configure your Git username and email.

Install Required Software

To set up a build environment, you need the following software installed:

Building

Install packages using the following command:

npm install

After installation, the following NPM scripts are available:

  • npm run lint - Executes linters
  • npm run build - Builds DevExtreme in the Debug mode
  • npm run build-dist - Builds DevExtreme in the Release mode
  • npm run build-themes - Use this script to rebuild CSS themes only

Build results are stored in the "artifacts" directory.

API Declarations

We use JSDoc-like syntax to declare the DevExtreme public API. The API declarations are then used to generate the API reference, the TypeScript declaration file (dx.all.d.ts), and integrate with 3rd party frameworks (Angular, React, Vue, and ASP.NET).

To modify API declarations, use the following NPM scripts:

  • npm run validate-declarations - Checks if DevExtreme API declarations are valid.
  • npm run update-ts - Updates TypeScript declarations according to API declarations. You should commit the updated dx.all.d.ts file. The CI checks if TypeScript declarations correspond to the declared API and notifies you if dx.all.d.ts is not up to date.

Tests and CI

We conduct extensive in-house testing of DevExtreme on different browsers, mobile devices, functional tests for demos, etc. However, we only share some of them on GitHub: linters and automated tests for Google Chrome.

Tests are in the testing directory, and you can execute them as described below:

Locally in Browser

Run "testing/launch" (for Mac and Linux) or "testing/launch.cmd" (for Windows). This command starts the testing server and opens the test running UI in the default web browser and is the primary way for development and debugging.

Locally in Docker

If you have Docker installed, you can run tests in the same environment as the online Continuous Integration. Use the following command:

docker run --rm -ti -e TARGET=test -v REPO_PATH:/devextreme devexpress/devextreme-build:TAG ./docker-ci.sh

Make the following replacements in the command line:

  • REPO_PATH - absolute path to the local git repository.
  • TAG - a Docker image tag. It should match the parent branch name (e.g. 16_2). You can find the list of available tags on our Docker Hub page.

The Dockerfile used to build "devexpress/devextreme-build" images is in the build/docker-image directory.

A VNC server is available within the running container. To track test execution, add the -p 5900:5900 parameter to the docker run command and connect to "localhost:5900" using any VNC client.

In a Cloud CI

We provide configuration YAML files for Travis CI (.travis.yml) and Shippable (shippable.yml). Enable one of them for your forked repo (we recommend Travis).

Please make sure that each pull request passes all automatic checks before submitting it.

Commit Message & Pull Request Title Guidelines

  • Use the imperative mood in the subject line
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Limit the subject line to 50 characters
  • If applicable, include an issue ID to the subject line. Feel free to use GitHub keywords to close the related issues automatically
  • Optionally, put any additional details, references, examples, etc. in the commit message body or PR description

Examples:

  • Mark dxCommand as DOMComponent child (TXXXXX)
  • Refactor ContextMenu after T560055 fix
  • Add namespace to doc comments (resolves #XXXX)
  • Fix editorFactory tests in IE