Contributing

We always welcome your contribution! This document provides how to contribute to cli-kintone.

Code of Conduct

Before starting contribution, please see Code of Conduct first.

Supporting resources

If you have any questions or feedbacks, you can check our supporting resources.

Issues

We use GitHub Issues for bug reports and feature requests.

Before submitting an Issue, please make sure that there is no related Issue already.

When creating an Issue, be sure to fill out the Issue template. Especially, a minimum reproduction is really important to fix a bug and directly lead to faster triage.

Pull Requests

If you are going to make a PR contribution, please make sure that a corresponding Issue exist first. In addition, we encourage you to make a proposal in the Issue before starting implementation.

Development

Setup repository

Node.js should be configured.

Clone and move into the repository

git clone git@github.com:kintone/cli-kintone.git
cd cli-kintone

Install dependencies

corepack enable
pnpm install

Run build command to check if the repository is ready.

pnpm build

Build

Currently, we have different build processes for the npm package and executables.

To build both of them, run build:all command:

pnpm build:all

Build npm package

Run build command:

pnpm build

To build in watch mode, run start command:

pnpm start

To check behavior, run the entrypoint file directly:

./cli.js

Build executables

Run build:artifacts command:

pnpm build:artifacts

Executables will be generated in bin directory.

bin
├── cli-kintone-linux-x64
├── cli-kintone-macos-arm64
└── cli-kintone-win-x64.exe

Testing

We have two kinds of tests, unit tests and E2E tests. You can view test reports generated by Allure Report.

Unit tests

When you change implementation, corresponding unit tests must be added or updated.

Unit tests are located in the __tests__ directory next to the test target code.

Please read Jest document to know how to write unit tests.

You can run unit tests using test command:

pnpm test

注記

We also run tests on CI, so local execution is optional.

E2E tests

E2E testing is based on practical scenarios. We use Cucumber.

All of our E2E tests are located in features directory of repository root.

You can run E2E tests using test:e2e command:

pnpm test:e2e

Unfortunately, an actual kintone environment with API access is required to run E2E tests. Therefore, we recommend to run on CI.

Parallel execution

E2E tests are executed in parallel by default to speed up test execution. The default configuration allows up to 10 tests to run concurrently.

In some cases, you may want to run tests sequentially. For example, when multiple tests share the same resource (such as a specific kintone app), they should not run at the same time to avoid conflicts.

To run a specific scenario sequentially, use the @serial tag with a resource identifier:

@serial(app_in_space_for_export)
Scenario: App in a space
  Given The app "app_in_space_for_export" has no records
  ...

Scenarios with the same @serial(resource) tag will not run concurrently with each other. However, they can still run in parallel with scenarios that have different @serial tags or no @serial tag at all.

Examples of resource identifiers used in existing E2E tests:

Resource Identifier	Description
app_for_export	General purpose app for testing record export functionality
app_for_import	General purpose app for testing record import functionality
app_for_export_attachments	App with attachment fields for testing file download functionality
app_for_export_table	App with table fields for testing table data export
app_in_space_for_export	App located in a kintone space for testing space-related features
app_in_guest_space	App located in a guest space for testing guest space access
plugin_<plugin_id>	Plugin resource for testing plugin upload/update functionality (e.g., plugin_chjjmgadianhfiopehkbjlfkfioglafk)

Multiple test scenarios that operate on the same resource should use the same @serial tag to prevent race conditions during parallel test execution.

For more details about parallel execution in Cucumber, see the official documentation.

Documentation website

The documentation website (this website!) must be updated in the same PR.

Edit files in website/docs to update documents.

To preview changes on local, run doc:start command:

pnpm doc:start

Internationalization (i18n)

The documentation website supports multiple languages. Currently, we support English (default) and Japanese.

Translation workflow

1. Update English documentation - Always update English docs first in website/docs/
2. Translate to Japanese - Add translations in website/i18n/ja/docusaurus-plugin-content-docs/current/
3. Update translation progress - Run the command to update the translation percentage in the language switcher:

cd website
pnpm update-translation-progress

This command will:

• Count English and Japanese documentation files
• Calculate translation percentage
• Update the language switcher label (e.g., "日本語 (28%)")

4. Preview both languages - Test your changes in both languages:

# English version
pnpm doc:start

# Japanese version
pnpm doc:start --locale ja

File structure

website/
├── docs/                      # English documentation (source)
│   ├── guide/
│   ├── reference/
│   └── community/
├── i18n/ja/                   # Japanese translations
│   └── docusaurus-plugin-content-docs/
│       └── current/           # Translated docs
│           ├── guide/
│           ├── reference/
│           └── community/

Translation guidelines

• Maintain structure - Keep the same file structure and frontmatter
• Use @site/ for imports - In translated files, use @site/ alias for React component imports:

  import Component from "@site/src/components/Component";

• Copy images - Copy images to the same relative path in the i18n directory
• Keep .md extensions - Use .md extension in internal links (e.g., [link](./page.md))
• Update regularly - Run pnpm update-translation-progress after adding translations

For more details about Docusaurus i18n, see the official documentation.

Linting

Before commit your work, please run lint command:

pnpm lint

You can run auto-fix with fix command:

pnpm fix

Stability

We define the Stability Index to indicate stability of features.

For experimental/deprecated features, please add admonitions on docs and show warnings on CLI.

Admonitions

To add admonitions, use experimental or deprecated admonition type.

:::experimental[Title]

Body

:::

Experimental: Title

Body

:::deprecated[Title]

Body

:::

Deprecated: Title

Body

CLI Warnings

To show warnings on CLI, use helper functions.

emitExperimentalWarning("This feature is under early development.");

emitDeprecationWarning(
  "This feature has been deprecated.\nUse new option instead.",
);

Commit

The commit message must follow the Conventional Commits.

<type>: <description>

We support the following commit types:

Type	Description
feat	New features
fix	Bug fixes
test	Test updates
build	Changes on build process
ci	Changes on CI workflows
docs	Document updates
perf	Performance improvements
refactor	Refactoring
revert	Reverting past changes
lint	Lint updates
style	Style updates
debug	Debugs
chore	Any other chores

警告

Must not merge debug commit to the main branch.

If the commit will change the backward compatibility, please mark the commit as a Breaking Change.

• Add ! just after the scope
• Add BREAKING CHANGE: <description> footer
  • The description should be a short clear summary of user impact.

Creating a Pull Request

When everything is ready, make a Pull Request on GitHub.

The PR title must also follow the Conventional Commits. The title will be used as the commit message of squash commit on merging. It will also be used on CHANGELOG, so make sure to be understandable for users.

Finally, don't forget to fill out the PR body following the template.

Releasing

We use Release Please to create a release and update CHANGELOG.

Merging a Release PR will trigger the release. Please check CHANGELOG and release version before merge.

Release frequency

Normally, maintainer will trigger a release weekly.

Versioning

We follow the Semantic Versioning.

For more details, see Versioning Policy page.