English | 한국어
Bug reports, documentation improvements and focused Kotlin changes are welcome. For vulnerabilities, follow SECURITY.md rather than posting details in an issue.
Clone the repository and check out develop. Use JDK 21 and the checked-in Gradle Wrapper. Linux checks also require Bash, jq, sha256sum and unzip on PATH.
git clone --branch develop https://github.com/oxspan/scouterctl.git
cd scouterctl
./gradlew testUse ./gradlew.bat test in Windows PowerShell. Ordinary tests use local fixtures; they do not require a Scouter account or download Collector distributions. While developing, select a focused test with --tests 'dev.scouterctl.CliOutputContractTest'.
To build and verify the Linux command package:
./gradlew verifyReleaseInputsFor a local Linux installation, use ./gradlew installDist and run build/install/scouterctl/bin/scouterctl. Native Windows packaging additionally requires the pinned toolchain; see releasing. Real Collector/Agent/Spring checks are opt-in and described in testing. Use local CI to run the workflow build with act when needed.
To generate coverage reports and enforce the line/branch minimums, run ./gradlew -Pcoverage=true coverageCheck. This includes the test JVM and CLI subprocesses. See testing for measurement scope and report locations.
Same-repository PRs receive a bot comment with Linux test counts, coverage/thresholds, the CI result and run links. Re-runs update the existing comment and outdated commits are skipped. Windows checks remain in the workflow; fork and Dependabot PRs receive the Actions summary and artifacts without a comment because their tokens are read-only.
- Implement CLI behavior in Kotlin. Use Kotest
FunSpecand matchers; JUnit Platform runs Kotest, while test APIs remain Kotest. The native Windows launcher is a separate platform boundary. - Follow the inward dependency rules in Architecture. Keep CLI parsing, JSON, files and network code outside core/application logic.
- Preserve the CLI output format and capture compatibility rules. Explain migrations when a change breaks either format.
- Test observable behavior with the existing fixtures and subprocess harnesses. Choose checks appropriate to the change; documentation-only edits do not need new runtime tests.
- Keep credentials, real captures, local configuration and generated evidence out of commits. Use synthetic, sanitized examples in reports and fixtures.
- Update the relevant English and Korean guides together when installation or usage changes.
| Change | Start from | PR target |
|---|---|---|
Feature, regular fix, tests or documentation (feature/<issue>[-<slug>]) |
develop |
develop |
Urgent release fix (hotfix/<issue>[-<slug>]) |
master |
master |
| Release-ready integration | develop |
master |
Use the issue number without #, as in feature/59. A short lowercase, hyphen-separated description is optional and recommended for readability, as in feature/59-object-list. For small maintenance changes without an issue, use feature/<slug>. Dependabot and release-please use their generated branch names.
Reference the issue with Refs #59 in a PR to develop. When the fix is included in a PR to master, use Closes #59 to close the issue on merge.
master is the default and release branch; develop integrates upcoming changes. Release branches are not currently used. Keep each PR focused and explain the problem, resulting behavior, validation actually performed, and compatibility risks.
Choose the base and compare branches before selecting English or 한국어 from the default PR description's Preview tab. Switching languages reloads the form, so select a language before writing the description. If GitHub restores a draft, open the language link in a new tab; reselect it after changing branches. Templates are loaded from the default branch. Alternatively, use a local template:
gh pr create --base develop --template .github/PULL_REQUEST_TEMPLATE/english.md
gh pr create --base develop --template .github/PULL_REQUEST_TEMPLATE/korean.mdUse one language per PR. See the English and Korean templates.
PRs to develop receive Linux tests and package checks. PRs to master also verify the same package and run tests on Windows. Check the latest revision's results before merging; local validation does not establish hosted CI success. See Local CI for the complete execution policy.
Use one intention-matched Gitmoji and a concise English subject for authored commits, such as ✨ Add offline inspection, 🐛 Preserve capture checkpoints, or 📝 Clarify installation.
Feature and hotfix PRs normally use squash merge. Give the PR a Conventional Commit title with the Gitmoji after the type, such as feat: ✨ Add offline inspection or fix: 🐛 Preserve capture checkpoints; use that title as the squash subject. feat requests a minor release, fix a patch, and ! marks a breaking change (a major release for the current stable series). docs, test, ci and chore do not request a release on their own.
Use merge commits for develop → master promotion and master → develop synchronization to preserve ancestry. A promotion title must reflect its release intent, such as feat: 🔀 Promote capture comparison; use chore: 🔀 Sync master into develop for synchronization. Keep generated release-please and Dependabot messages intact.
Maintainers: see Release maintenance for versioning, release PRs, platform gates and interrupted-upload recovery. version.txt is the build version source; do not edit release tags or version metadata as an incidental contribution change.