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
├── cli-kintone-macos
└── cli-kintone-win.exe
Testing
We have two kinds of tests, unit tests and E2E tests.
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.
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
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
:::
Body
:::deprecated[Title]
Body
:::
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.