Skip to main content

Develop

Initialization​

Install dependencies​

Currently we use yarn to manage project dependencies, so you need to install yarn correctly before you start. If you haven't installed yarn, you can find detailed installation methods in yarn installation guide.

Install dependencies
yarn

Code generation​

After installing the dependencies, we need to generate some necessary type files so that test, typecheck and code style check can work correctly.

Code generation
yarn codegen

Start development server​

Start development server manually​

note

If you choose to start the development server manually, you need to refer to the project architecture section for the following dependencies to be installed correctly and in a usable state:

Perfsee is composed of many components and services, but in the daily development process, the most common ones are these three:

You can choose the service you need to develop, and then start it independently:

# Start backend service, default listening to port 3000, access through http://localhost:3000
yarn dev -p @perfsee/platform-server

Docker compose​

If you prefer to use tools like Docker to manage the development environment, we have already configured a docker-compose.yml file for you, you can easily start the entire development environment without worrying about system dependencies:

Docker compose
# Since docker compose v2 does not follow the `depends_on` dependency relationship to sequentially build images, you need to build all the images you need separately.
# See: https://github.com/docker/compose/issues/9686
docker compose build
docker compose up

Test​

We choose ava as the test framework. You can refer to its documentation to learn how to write test cases.

All test cases should be placed in the __tests__ folder next to the component or function being tested, and use .spec.ts or .spec.e2e.ts as the suffix to facilitate searching.

If the test case has unpredictable side effects when running in parallel, such as reading and writing databases, then it should use .spec.e2e.ts or .spec.serial.ts as the suffix, and mark it as a test case that can only be run serially.

# Run all test cases
yarn test

# Only run test cases with `.spec.ts` suffix
yarn ava

# Only run test cases with `.spec.{e2e,serial}.ts` suffix
yarn ava -s

Code style​

We use ESLint and Prettier to enforce code style:

yarn lint

And use TypeScript to perform strong type checking:

yarn typecheck

Commit​

We use commitlint to enforce commit message format, please refer to its documentation for details.

In general, all commit messages should follow the following format:

type(scope?): subject

type depends on the content of the commit, such as feat for adding new features, fix for fixing bugs, ci for CI related changes, etc. You can find a complete list in commitlint.

scope can be a package name or a folder name, used to summarize the package involved in the commit.

subject is a short description of the commit content.

Here are some real world examples:

feat(platform): add a retry button on failed job
fix(job-runner): random panic when spawning workers
chore: bump up dependencies

We strongly recommend that each commit only includes the changes of on simple thing, and do not mix unrelated modifications together.

Versioning​

Thanks to conventional-changelog, we can easily generate changelogs and select appropriate version numbers for the next package release based on readable commit messages.

yarn release

Deployment​

Since the deployment progress is quite complicated, we will describe in detail how to deploy the Perfsee to the production environment in a separate deployment document.