Compare commits

...
63 Commits
Author SHA1 Message Date
james.maes 5271b5bfa5 Merge branch 'develop' 2026-01-18 08:39:43 -06:00
james.maes d3e1891725 fix: skip version commit for feature branches 2026-01-18 08:12:52 -06:00
james.maes 0eab936d85 fix(static_analysis): use mvn install for multi-module dependency resolution
Static analysis needs artifacts in local repo for inter-module deps.
2026-01-14 13:58:26 -06:00
james.maes 04888150fd build: cleaned up linting errors 2026-01-14 13:58:26 -06:00
james.maes 43fcfe1213 feat(orb): added spotbugs and pmd workflows 2026-01-14 13:58:26 -06:00
james.maes fec302d58d fix(static_analysis): use mvn install for multi-module dependency resolution
Static analysis needs artifacts in local repo for inter-module deps.
2026-01-14 13:47:34 -06:00
james.maes dabfcce4ad build: cleaned up linting errors 2026-01-14 13:30:15 -06:00
james.maes 3ffe371af2 feat(orb): added spotbugs and pmd workflows 2026-01-14 13:27:07 -06:00
james.maes 34688a1a53 Merge branch 'develop' 2026-01-10 20:43:05 -06:00
james.maes 6d181f361b fix: npm prerelease tags and skip GitHub release for RCs 2026-01-10 20:41:49 -06:00
james.maes d4ba7722c7 Merge branch 'develop' 2026-01-09 13:34:16 -06:00
james.maes 43ccb6ced0 fix: make version commit push failures non-fatal 2026-01-07 10:04:44 -06:00
james.maes b34cde9d19 fix(surefire-reports): Strip rerunFailure elements that CircleCI's JUnit parser doesn't support 2026-01-07 08:55:56 -06:00
james.maes 19deffb20e Merge branch 'develop' 2026-01-07 08:31:49 -06:00
james.maes a50948c1af docs(changelog): Added 0.5.1 changes 2026-01-07 08:31:14 -06:00
james.maes 7c79a57a8a fix(frontend_test_dependencies): updated Installing browser dependencies to ensure that it works noninteractive 2026-01-07 08:20:59 -06:00
james.maes aa4442618b chore: migrate license from AGPL-3.0 to Apache-2.0 2026-01-05 10:18:00 -06:00
james.maes 825937776c fix(gitignore): added local claude settings 2025-12-29 07:47:57 -06:00
james.maes 41702b0a30 docs(changelog): add missing versions 0.3.9-0.3.13 and fix dates 2025-12-29 07:46:01 -06:00
james.maes b3c6f237ee build(claude): removed local settings 2025-12-29 06:46:17 -06:00
james.maes 6649766a51 docs: update for v0.5.0 release 2025-12-28 11:33:10 -06:00
james.maes 342646a856 docs: update README for machine executor and Docker support 2025-12-28 11:29:06 -06:00
james.maes c43666fb4c feat: switch to machine executor for Docker support
Replace cimg/openjdk Docker executor with Ubuntu machine executor
that has native Docker support. This enables Testcontainers and
LocalStack Docker extension tests to run properly in CI.

- Create install_java command to install Temurin JDK and Maven
- Add optional Node.js installation for frontend builds
- Update all Maven jobs to use machine executor
2025-12-28 11:15:06 -06:00
james.maes eff82e0ffd revert: remove setup_remote_docker (not needed) 2025-12-28 08:56:46 -06:00
james.maes a1c797d897 feat: add setup_remote_docker for Docker-dependent tests 2025-12-28 08:46:14 -06:00
james.maes 76f37ad23a build(claude): added settings 2025-12-28 08:33:16 -06:00
james.maes b1523223d0 Merge main into develop 2025-12-28 08:32:17 -06:00
james.maes 09db303b9b fix(git): use CircleCI checkout for SSH/known_hosts handling 2025-12-28 08:31:35 -06:00
james.maes eedc21aeff fix(git): add GitHub SSH host key before clone 2025-12-28 08:23:58 -06:00
james.maes f23015ff1e fix(orb): update URLs to valid QRun-IO GitHub repo 2025-12-28 08:22:31 -06:00
james.maes b4a6aa0d4c docs: update for v0.4.0 release
- Add CHANGELOG entry for v0.4.0
- Update README to follow QQQ repo standards
- Add CLAUDE.md for Claude Code guidance
2025-12-28 08:15:58 -06:00
james.maes a347ddd68b Merge branch 'develop' 2025-12-28 08:06:18 -06:00
james.maes f6e04f7a58 style(makefile): fixed formatting 2025-12-28 08:05:19 -06:00
james.maes 5580d51cf7 feat: add Java 21 support with configurable executor (#4)
- Add java executor using cimg/openjdk with configurable version
- Update Maven jobs to use java executor with java_version parameter
- Update Node jobs to use default executor with node_version parameter
- Remove localstack orb dependency (no longer needed)
- Default Java version: 21.0 (use 17.0 for older projects)
2025-12-28 08:04:26 -06:00
james.maes eb9de5db69 chore(license): change to AGPL-3.0 with QRun-IO copyright 2025-12-25 19:35:16 -06:00
james.maes 3f5dd9a746 feat(release): add RC support for GitHub release creation 2025-12-24 21:46:38 -06:00
james.maes 65787b7dd2 feat(release): add automatic GitHub release creation
- Update create_github_release.sh to use CircleCI env vars for repo detection
- Add artifact links to Maven Central and npmjs in release notes
- Support both Maven and Node projects with auto-detection
- Add publish_github_release command wrapper
- Integrate into mvn_publish and node_publish jobs for release/hotfix branches
2025-12-24 20:16:44 -06:00
james.maes 4f07167e26 docs: Standardize README 2025-12-24 14:21:42 -06:00
james.maes 84a0e345b9 ci: Add GitHub release configuration 2025-12-24 12:44:44 -06:00
james.maes a1ef2a419f style(lint): spacing cleanup for lint 2025-10-22 08:38:34 -05:00
james.maes 99a776ee2a fix(calulate_version): updated to use circle-ci branch env before failing back to git ref parsing 2025-10-22 08:37:37 -05:00
james.maes 5b167ca8f8 fix(cache): seperated saves and cache restores by key 2025-10-09 16:42:41 -05:00
james.maes 43247349d7 fix(frontend_build): fixed cache steps in frontend_test part of workflow 2025-10-09 16:36:40 -05:00
james.maes 4486188522 hotfix from develop - frontend build 2025-10-09 16:18:04 -05:00
james.maes 1232a17f36 fix(frontend_build): updated save cache to also save npm module cache 2025-10-09 16:14:28 -05:00
james.maes 1f2e730512 Merge pull request #3 from Kingsrook/feature/snapshot-releases
Feature/snapshot releases
2025-09-29 11:22:04 -05:00
james.maes 2b59dac369 style(git-operations): converted to our internal git-operations command 2025-09-29 11:19:58 -05:00
james.maes 22fa420c52 docs: updated documents for release of 3.8 2025-09-29 11:07:58 -05:00
james.maes f337e2ff51 fix(circleci): updated publish jobs to skip git_operations for feature snapshot builds 2025-09-29 11:01:27 -05:00
james.maes 9d1a70e433 fix(calculate_version): fixed leading whitespaces issues on feature branch detection 2025-09-29 10:53:38 -05:00
james.maes 145c99e2f8 fix(git_full_checkout): removed depth - default to full 2025-09-29 10:47:04 -05:00
james.maes 8792d74fb0 fix(git-checkout): converting to a custom command to get full git clones 2025-09-29 10:45:17 -05:00
james.maes 5b5df41faa fix(git-checkout): updated depth to 10 2025-09-29 10:40:36 -05:00
james.maes 59c80f756a fix(git-checkout): updated to use command to get full clone 2025-09-29 10:34:26 -05:00
james.maes 187d0df5c7 ci(git-checkout): feature name detection was failing due to shallow git checkout clones, updated to be full clones 2025-09-29 10:30:56 -05:00
james.maes aa5cab7390 test: updated publish tag tests 2025-09-22 08:55:17 -05:00
james.maes f2d8a9927a fix(calulate_version): updated handling for finding feature name from a publish tag 2025-09-22 08:51:48 -05:00
james.maes 8820a7af82 fix(calulate_version): fixed support for tags on feature branches and added tests 2025-09-22 08:44:11 -05:00
james.maes 8adb9e65f7 fix: Linting updates 2025-09-20 09:38:23 -05:00
james.maes 492af48c0d docs: updated changelog and example build files 2025-09-20 09:12:23 -05:00
james.maes ae26b2288a feat: adding support for publishing snapshots for feature branches
Support Feature Snapshot Releases #1
2025-09-20 09:06:55 -05:00
james.maes f122b4a470 chore: Removed ignored file 2025-09-20 07:25:44 -05:00
james.maes ea30ebdb2f chore: Added IDE to ignore 2025-09-20 07:25:03 -05:00
43 changed files with 1659 additions and 701 deletions

No files matched your search

+31
View File
@@ -0,0 +1,31 @@
# GitHub Release Configuration
# Auto-generates release notes from PR labels
changelog:
exclude:
labels:
- ignore-for-release
- duplicate
- invalid
authors:
- dependabot
- dependabot[bot]
categories:
- title: Breaking Changes
labels:
- breaking-change
- breaking
- title: New Features
labels:
- enhancement
- feature
- title: Bug Fixes
labels:
- bug
- fix
- title: Dependencies
labels:
- dependencies
- title: Other Changes
labels:
- "*"
+5
View File
@@ -5,3 +5,8 @@ target
# Test data directory (created dynamically during tests)
tests/test_data
# IDE
.idea
.claude
-120
View File
@@ -1,120 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="AutoImportSettings">
<option name="autoReloadType" value="SELECTIVE" />
</component>
<component name="ChangeListManager">
<list default="true" id="39f8d35a-1bb7-489b-b59c-b0ba3ffefe23" name="Changes" comment="">
<change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/calculate-version.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/calculate-version.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/check_middleware_api_versions.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/check_middleware_api_versions.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/create_github_release.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/create_github_release.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/manage_version_calculate.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/manage_version_calculate.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/manage_version_commit.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/manage_version_commit.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/manage_version_git_config.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/manage_version_git_config.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/mvn_build_compile.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/mvn_build_compile.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/mvn_jar_deploy_deploy.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/mvn_jar_deploy_deploy.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/mvn_jar_deploy_gpg_setup.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/mvn_jar_deploy_gpg_setup.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/mvn_verify_save_test_results.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/mvn_verify_save_test_results.sh" afterDir="false" />
<change beforePath="$PROJECT_DIR$/src/scripts/mvn_verify_verify.sh" beforeDir="false" afterPath="$PROJECT_DIR$/src/scripts/mvn_verify_verify.sh" afterDir="false" />
</list>
<option name="SHOW_DIALOG" value="false" />
<option name="HIGHLIGHT_CONFLICTS" value="true" />
<option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
<option name="LAST_RESOLUTION" value="IGNORE" />
</component>
<component name="Git.Settings">
<option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
</component>
<component name="GitHubPullRequestSearchHistory">{
&quot;lastFilter&quot;: {
&quot;state&quot;: &quot;OPEN&quot;,
&quot;assignee&quot;: &quot;KofTwentyTwo&quot;
}
}</component>
<component name="GithubPullRequestsUISettings">{
&quot;selectedUrlAndAccountId&quot;: {
&quot;url&quot;: &quot;git@github.com:Kingsrook/qqq-orb.git&quot;,
&quot;accountId&quot;: &quot;7a0b7646-5b0c-4647-976d-932a62661dd2&quot;
}
}</component>
<component name="MacroExpansionManager">
<option name="directoryName" value="Qi1Hqxgr" />
</component>
<component name="ProjectColorInfo">{
&quot;associatedIndex&quot;: 5
}</component>
<component name="ProjectId" id="32YtZdjn4FeSrJsD5VMG3tLBHKD" />
<component name="ProjectLevelVcsManager">
<ConfirmationsSetting value="2" id="Add" />
</component>
<component name="ProjectViewState">
<option name="autoscrollFromSource" value="true" />
<option name="showExcludedFiles" value="false" />
<option name="showLibraryContents" value="true" />
</component>
<component name="PropertiesComponent">{
&quot;keyToString&quot;: {
&quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
&quot;RunOnceActivity.git.unshallow&quot;: &quot;true&quot;,
&quot;RunOnceActivity.go.formatter.settings.were.checked&quot;: &quot;true&quot;,
&quot;RunOnceActivity.go.migrated.go.modules.settings&quot;: &quot;true&quot;,
&quot;SHARE_PROJECT_CONFIGURATION_FILES&quot;: &quot;true&quot;,
&quot;git-widget-placeholder&quot;: &quot;develop&quot;,
&quot;go.import.settings.migrated&quot;: &quot;true&quot;,
&quot;io.aesy.yamllint.do.not.ask.to.enable&quot;: &quot;true&quot;,
&quot;last_opened_file_path&quot;: &quot;/Users/james.maes/Git.Local/Kingsrook/qqq-orb/src/jobs&quot;,
&quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
&quot;node.js.selected.package.eslint&quot;: &quot;(autodetect)&quot;,
&quot;nodejs_package_manager_path&quot;: &quot;npm&quot;,
&quot;org.rust.cargo.project.model.impl.CargoExternalSystemProjectAware.subscribe.first.balloon&quot;: &quot;&quot;,
&quot;org.rust.first.attach.projects&quot;: &quot;true&quot;,
&quot;settings.editor.selected.configurable&quot;: &quot;preferences.sourceCode.yaml&quot;
},
&quot;keyToStringList&quot;: {
&quot;stardust.markdown.MarkdownSplitEditorSuppressor:keyList&quot;: []
}
}</component>
<component name="RecentsManager">
<key name="CopyFile.RECENT_KEYS">
<recent name="$PROJECT_DIR$/src/jobs" />
<recent name="$PROJECT_DIR$/src/commands" />
</key>
</component>
<component name="RustProjectSettings">
<option name="toolchainHomeDirectory" value="$USER_HOME$/.cargo/bin" />
</component>
<component name="SharedIndexes">
<attachedChunks>
<set>
<option value="bundled-jdk-9823dce3aa75-bf35d07a577b-intellij.indexing.shared.core-IU-252.25557.131" />
<option value="bundled-js-predefined-d6986cc7102b-b598e85cdad2-JavaScript-IU-252.25557.131" />
</set>
</attachedChunks>
</component>
<component name="TaskManager">
<task active="true" id="Default" summary="Default task">
<changelist id="39f8d35a-1bb7-489b-b59c-b0ba3ffefe23" name="Changes" comment="" />
<created>1757609391348</created>
<option name="number" value="Default" />
<option name="presentableId" value="Default" />
<updated>1757609391348</updated>
<workItem from="1757609392578" duration="5983000" />
<workItem from="1757633227531" duration="300000" />
<workItem from="1757633543711" duration="945000" />
<workItem from="1757634532876" duration="26000" />
<workItem from="1757634568948" duration="111000" />
<workItem from="1757634683262" duration="86000" />
<workItem from="1757634778652" duration="275000" />
<workItem from="1757635061044" duration="63000" />
<workItem from="1757721395861" duration="3728000" />
</task>
<servers />
</component>
<component name="TypeScriptGeneratedFilesManager">
<option name="version" value="3" />
</component>
<component name="VgoProject">
<settings-migrated>true</settings-migrated>
</component>
</project>
+8
View File
@@ -0,0 +1,8 @@
repos:
- hooks:
- id: commitizen
- id: commitizen-branch
stages:
- pre-push
repo: https://github.com/commitizen-tools/commitizen
rev: v4.9.1
+137 -19
View File
@@ -5,9 +5,78 @@ All notable changes to QQQ Orb will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.5.1] - 2026-01-07
### Fixed
- Added `DEBIAN_FRONTEND=noninteractive` to browser dependency installation to prevent interactive prompts from blocking CI
- Strip `<rerunFailure>` elements from JUnit XML before upload to fix CircleCI test result parsing errors
- Version commit push failures no longer fail the build (handles race conditions between concurrent builds)
## [0.5.0] - 2025-12-28
### Added
- Machine executor with native Docker support for Testcontainers and LocalStack
- `install_java` command to install Temurin JDK and Maven on machine executors
- Optional Node.js installation for frontend builds on machine executor
### Changed
- Switched from Docker executor (cimg/openjdk) to Ubuntu machine executor
- All Maven jobs now use machine executor with Docker pre-installed
### Fixed
- GitHub SSH host key added before clone operations
## [0.4.0] - 2025-12-28
### Added
- Java 21 support with configurable executor - New `java` executor using `cimg/openjdk` with version parameter (default: 21.0)
- Automatic GitHub release creation for releases and release candidates
- RC support for GitHub releases (published as pre-releases)
### Changed
- License changed to AGPL-3.0 with QRun-IO copyright
- Maven jobs now use the new `java` executor (resource_class: large)
- Node jobs use `default` executor with configurable version
### Migration
Projects needing Java 17 can explicitly set `java_version: "17.0"` in their workflow config.
## [0.3.13] - 2025-12-28
### Added
- GitHub release configuration for CI pipeline
- Standardized README documentation
### Changed
- Merged develop branch updates in preparation for 0.4.0
## [0.3.12] - 2025-10-22
### Fixed
- Version calculation now uses `CIRCLE_BRANCH` environment variable before falling back to git ref parsing
### Changed
- Linting cleanup for spacing consistency
## [0.3.11] - 2025-10-09
### Fixed
- Separated cache saves and restores by key for proper cache isolation
## [0.3.10] - 2025-10-09
### Fixed
- Frontend build cache steps in test workflow corrected
## [0.3.9] - 2025-10-09
### Fixed
- Frontend build now properly saves npm module cache
## [0.3.8] - 2025-09-29
### Added
- Support for publishing snapshots for feature branches
- Comprehensive README with detailed usage examples
- CONTRIBUTING.md with development guidelines
- SECURITY.md with security policy and reporting procedures
@@ -17,40 +86,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Updated README to follow QQQ framework standards
- Enhanced documentation structure and organization
## [2.1] - 2024-01-XX
## [0.3.7] - 2025-09-18
### Added
- Multi-platform support for Maven and Node.js projects
- GitFlow integration with automated version management
- Comprehensive testing framework with coverage reporting
- Automated publishing to Maven Central and npm registries
- Shell script automation and utilities
- Documentation generation and publishing
- Comprehensive README with current functionality and testing framework documentation
### Changed
- Improved orb structure and organization
- Enhanced error handling and validation
- Updated dependencies and security patches
- Enhanced documentation structure and organization
## [0.3.6] - 2025-09-16
### Fixed
- Various bug fixes and stability improvements
- Updated handling for tagged releases in main branch to properly promote to latest tag
- Fixed git commit operations on main branch for production releases
## [2.0] - 2023-XX-XX
## [0.3.5] - 2025-09-16
### Fixed
- Updated git commit on main branch to work correctly for tag releases in production releases
## [0.3.4] - 2025-09-15
### Fixed
- Removed conditionals around git operations after version checks for main and hotfix branches
- Updated standard GitHub documentation to point to top-level project documentation
## [0.3.3] - 2025-09-15
### Added
- Made publish_asciidoc a parameterized run option
### Changed
- Enhanced parameterization for better flexibility
## [0.3.2] - 2025-09-15
### Added
- Base level repository files and updated README
### Changed
- Updated check_middleware_api_versions to run based on parameter configuration
## [0.3.1] - 2025-09-15
### Fixed
- Version bump corrections
- Fixed bad sync RC update
- Updated example version references
## [0.3.0] - 2025-09-15
### Added
- Support for pure Node.js projects
- Support for building integrated frontend (npm) within Maven projects
- Support for publishing snapshots and tags
- Enhanced feature branch versioning with dynamic commit hash updates
- Comprehensive test suite and improved linting for calculate_version.sh
### Changed
- Reverted to only handle POM files (npm handled within its own job)
- Adjusted default execution state for scripts
- Converted longer commands to scripts per organization linting standards
- Refactored calculate_version.sh for cleaner branch level code
### Fixed
- Multiple linting fixes from CircleCI integration
- Improved error handling and validation
## [0.2.0] - 2025-09-13
### Added
- Initial CircleCI orb implementation
- Basic Maven project support
- Core CI/CD workflows
- Initial documentation for orb
### Changed
- Migrated from custom CI/CD to CircleCI orbs
- Updated CircleCI to use new QQQ orb for workflows
## [1.x] - 2022-XX-XX
### Added
- Legacy CI/CD implementation
- Basic automation scripts
### Fixed
- Implemented initial linting fixes from CircleCI
- Initial import of scripts and jobs from QQQ base repository
---
**Note**: For detailed release information and breaking changes, see the [QQQ Wiki](https://github.com/Kingsrook/qqq/wiki).
**Note**: For detailed release information and breaking changes, see the [QQQ Wiki](https://github.com/Kingsrook/qqq/wiki).
+82
View File
@@ -0,0 +1,82 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
CircleCI orb for QQQ framework projects. Provides pre-built jobs for building, testing, and publishing Maven and Node.js projects using GitFlow branching strategy.
## Build Commands
```bash
make pack # Pack orb to target/qqq-orb-packed.yml
make validate # Pack and validate orb
make test # Pack and validate (alias for validate)
make test-scripts # Run calculate_version.sh test suite
make test-all # Run all tests (orb + scripts)
make lint # Run yamllint, shellcheck, and CircleCI validation
make dev # Development workflow: pack, validate, show status
make clean # Remove target/ and tests/test_data/
make publish-snapshot # Publish to kingsrook/qqq-orb@dev:snapshot
make publish-release # Interactive production release with git tagging
```
## Running Individual Tests
```bash
./tests/run_tests.sh # Standard test run
./tests/run_tests.sh --verbose # Verbose output
./tests/run_tests.sh --ci # CI mode (minimal output)
./tests/test_calculate_version.sh # Direct test suite execution
```
## Architecture
### Directory Structure
- `src/@orb.yml` - Main orb definition entry point
- `src/commands/` - Reusable orb commands (YAML files that include scripts)
- `src/jobs/` - Complete job definitions combining commands
- `src/executors/` - Docker executor definitions (java.yml, default.yml)
- `src/scripts/` - Bash scripts included in commands
- `tests/` - Test suite for calculate_version.sh
### Key Components
**Executors:**
- `java` - cimg/openjdk image with configurable version (17.0, 21.0), resource_class: large
- `default` - cimg/node image for Node.js projects
**Jobs:**
- `mvn_publish` - Full publish workflow (build, version, test, deploy, git ops, GitHub release)
- `mvn_test_only` - Build and test for feature branches
- `mvn_frontend_publish` / `mvn_frontend_test_only` - Same with frontend support
- `node_publish` / `node_test_only` - Pure Node.js workflows
**Version Calculation:**
The core logic is in `src/scripts/calculate_version.sh`. It determines version based on branch type:
- `develop` -> `X.Y.Z-SNAPSHOT`
- `release/*` -> `X.Y.Z-RC.N`
- `main` (tagged) -> `X.Y.Z`
- `hotfix/*` -> Patch version bump
- `feature/*` -> `X.Y.Z-feature-{name}-{hash}-SNAPSHOT`
### Orb Packing
The orb uses CircleCI's "unpacked" format. YAML files in `src/` are packed into a single `target/qqq-orb-packed.yml`. Commands reference scripts via `<<include(scripts/scriptname.sh)>>` syntax.
### CI Pipeline
`.circleci/config.yml` runs lint/pack/review/shellcheck, then continues to `.circleci/test-deploy.yml` which runs command tests and publishes on release tags (`v*.*.*`).
## Linting Requirements
- YAML: yamllint for commands/jobs/examples
- Shell: shellcheck for all .sh files in src/scripts/ and tests/
- Orb: `circleci orb validate` for orb syntax
## Required Context Variables for Publishing
- `MAVEN_USERNAME`, `MAVEN_PASSWORD` - Sonatype credentials
- `GPG_PRIVATE_KEY_B64`, `GPG_KEYNAME`, `GPG_PASSPHRASE` - GPG signing
- `GITHUB_TOKEN` - GitHub API access
+187 -17
View File
@@ -1,21 +1,191 @@
MIT License
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
Copyright (c) 2021-2024 Kingsrook, LLC
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
1. Definitions.
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to the Licensor for inclusion in the Work by the copyright
owner or by an individual or Legal Entity authorized to submit on
behalf of the copyright owner. For the purposes of this definition,
"submitted" means any form of electronic, verbal, or written
communication sent to the Licensor or its representatives, including
but not limited to communication on electronic mailing lists, source
code control systems, and issue tracking systems that are managed by,
or on behalf of, the Licensor for the purpose of discussing and
improving the Work, but excluding communication that is conspicuously
marked or otherwise designated in writing by the copyright owner as
"Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Copyright 2022-2025 QRunIO, LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
+1 -1
View File
@@ -19,7 +19,7 @@ help:
@echo " make publish-release - Interactive production release (tagged version)"
@echo ""
@echo "Key Files:"
@echo " src/@orb.yml - Main orb definition"
@echo " src/@orb.yml - Main orb definition"
@echo " target/qqq-orb-packed.yml - Packed orb (generated)"
# Pack the orb using the correct command for orb development
+6
View File
@@ -0,0 +1,6 @@
QQQ CircleCI Orb
Copyright 2022-2025 QRunIO, LLC
This product includes software developed at QRunIO, LLC (https://qrun.io/).
Licensed under the Apache License, Version 2.0.
+73 -348
View File
@@ -1,393 +1,118 @@
# QQQ Orb
# qqq-orb
[![CircleCI Orb](https://img.shields.io/badge/CircleCI%20Orb-kingsrook%2Fqqq--orb-blue.svg)](https://circleci.com/developer/orbs/orb/kingsrook/qqq-orb)
[![Version](https://img.shields.io/badge/version-2.1-blue.svg)](https://circleci.com/developer/orbs/orb/kingsrook/qqq-orb)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
CircleCI orb for QQQ framework projects.
> **CircleCI Orb for QQQ Framework Projects**
**For:** Teams using CircleCI to build, test, and publish QQQ applications
**Status:** Stable (v0.5.0)
CircleCI orb for Maven and Node.js projects using GitFlow. Provides automated building, testing, version management, and publishing to Maven Central and npm registries.
## Why This Exists
## 🚀 Overview
QQQ projects share common CI/CD patterns: build with Maven, run tests, publish to Maven Central or npm. Setting this up from scratch means duplicating workflow configuration across every repository.
QQQ Orb is a **CircleCI orb** that provides standardized CI/CD workflows for projects in the QQQ ecosystem. It handles the complete development lifecycle from building and testing to publishing releases.
This orb provides pre-built jobs for the complete QQQ development lifecycle. Add a few lines of YAML and your project has automated testing, version management, and publishing.
### What This Repository Contains
## Features
- **CircleCI Orb**: Reusable CI/CD workflows and commands
- **GitFlow Integration**: Automated branching and version management with intelligent version calculation
- **Multi-Platform Support**: Maven (Java) and npm (Node.js) project support
- **Publishing Automation**: Automated publishing to Maven Central and npm
- **Comprehensive Testing**: Full test suite with dynamic test environments
- **Quality Gates**: Enforced linting, testing, and validation before publishing
- **Maven and npm support** - Builds Java and Node.js projects
- **Docker-native execution** - Machine executor with Docker pre-installed for Testcontainers/LocalStack
- **GitFlow integration** - Automated versioning based on branch type
- **Publishing automation** - Maven Central and npm registry publishing
- **Test coverage** - JaCoCo integration with coverage reporting
- **Version calculation** - Semantic versioning with SNAPSHOT, RC, and release support
- **Java 21 default** - Temurin JDK with configurable version (17, 21)
### What This Repository Does NOT Contain
## Quick Start
- **QQQ Framework**: The actual low-code engine and backend
- **Application Code**: Business logic or application-specific code
- **Runtime Dependencies**: Libraries or frameworks used by applications
## 🏗️ Architecture
### Technology Stack
- **CircleCI Orbs**: Reusable configuration components
- **GitFlow**: Branching strategy for release management
- **Maven**: Java project build and dependency management
- **npm**: Node.js package management
- **Shell Scripts**: Automation and utility scripts with comprehensive testing
- **YAML**: Configuration and workflow definitions
### Core Capabilities
- **Automated Building**: Maven and npm project compilation
- **Testing**: Unit tests, integration tests, and coverage reporting
- **Intelligent Version Management**: Automated semantic versioning based on GitFlow with feature branch support
- **Publishing**: Maven Central and npm registry publishing with quality gates
- **Documentation**: Automated documentation generation and publishing
## 🚀 Quick Start
### Using the Orb
**Prerequisites:** CircleCI account, repository connected to CircleCI
```yaml
# .circleci/config.yml
version: 2.1
orbs:
qqq-orb: kingsrook/qqq-orb@2.1
qqq-orb: kingsrook/qqq-orb@0.5
workflows:
test_only:
filters:
branches:
ignore: [develop, main, /release\/.*/, /hotfix\/.*/]
build_and_test:
jobs:
- qqq-orb/build
- qqq-orb/test:
requires: [qqq-orb/build]
- qqq-orb/mvn_test_only
publish_snapshot:
filters: { branches: { only: develop } }
when:
equal: [develop, << pipeline.git.branch >>]
jobs:
- qqq-orb/publish:
- qqq-orb/mvn_publish:
context: qqq-maven-registry-credentials
branch_type: snapshot
publish_release_candidate:
filters: { branches: { only: /release\/.*/ } }
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: release_candidate
production_release:
filters: { branches: { only: main } }
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: release
hotfix_release:
filters: { branches: { only: /hotfix\/.*/ } }
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: hotfix
```
### Required Context
## Usage
Set up `qqq-maven-registry-credentials` context in CircleCI:
### Available Jobs
| Variable | Description | Required For |
|----------|-------------|--------------|
| `MAVEN_USERNAME` | Sonatype username | Maven publishing |
| `MAVEN_PASSWORD` | Sonatype password | Maven publishing |
| `GPG_PRIVATE_KEY_B64` | Base64 encoded GPG private key | Maven signing |
| `GPG_KEYNAME` | GPG key identifier | Maven signing |
| `GPG_PASSPHRASE` | GPG passphrase | Maven signing |
| `GITHUB_TOKEN` | GitHub API token | GitHub releases |
| `RDBMS_PASSWORD` | Database password | Integration testing |
| Job | Purpose |
|-----|---------|
| `mvn_test_only` | Build and test Maven projects |
| `mvn_publish` | Build, test, and publish Maven artifacts |
| `mvn_frontend_test_only` | Build and test Maven projects with npm frontend |
| `mvn_frontend_publish` | Build, test, and publish Maven projects with npm frontend |
| `node_test_only` | Build and test Node.js projects |
| `node_publish` | Build, test, and publish Node.js packages |
### Project Requirements
### Branch Types
- **Maven Projects**: `pom.xml` with `<revision>` property
- **Node.js Projects**: `package.json` with version field
- **Settings**: `/tmp/circleci/mvn-settings.xml` (auto-generated if missing)
- **Documentation**: `docs/index.adoc` (optional, for documentation)
| Branch | Version Format |
|--------|----------------|
| `develop` | `1.5.0-SNAPSHOT` |
| `release/1.5` | `1.5.0-RC.1` |
| `main` | `1.5.0` (requires tag) |
| `hotfix/1.5.1` | `1.5.1` |
| `feature/*` | `1.5.0-feature-abc1234-SNAPSHOT` |
## 📁 Repository Structure
### Java Version
```
src/
├── @orb.yml # Main orb definition
├── commands/ # Reusable commands
│ ├── mvn_build.yml # Maven build command
│ ├── mvn_verify.yml # Maven test and verify
│ ├── mvn_jar_deploy.yml # Maven deployment
│ ├── node_build_package.yml # Node.js build and package
│ ├── node_publish.yml # npm publishing
│ └── ... # Additional commands
├── jobs/ # Complete workflow jobs
│ ├── mvn_publish.yml # Maven publishing workflow
│ ├── mvn_test_only.yml # Maven testing workflow
│ ├── node_publish.yml # npm publishing workflow
│ └── node_test_only.yml # npm testing workflow
├── scripts/ # Shell scripts
│ ├── calculate_version.sh # Intelligent version calculation
│ ├── mvn_build_compile.sh # Maven compilation
│ ├── node_npm_auth.sh # npm authentication
│ └── ... # Additional scripts
├── executors/ # Execution environments
│ └── default.yml # Default executor configuration
└── examples/ # Usage examples
└── build.yml # Example configuration
Maven jobs run on Ubuntu machine executors with Temurin JDK. Default is Java 21. To use Java 17:
tests/ # Comprehensive test suite
├── test_calculate_version.sh # Version calculation tests
├── run_tests.sh # Test runner with CI support
└── README.md # Test documentation
```yaml
jobs:
- qqq-orb/mvn_test_only:
java_version: "17"
```
## 🎯 Available Jobs
### Docker Support
| Job | Branch | Output | Description |
|-----|--------|--------|-------------|
| `build` | Any | Compiled artifacts | Build project without testing |
| `test` | Any | Test results + JaCoCo | Run tests with coverage |
| `publish` | Any | Published artifacts | Unified publishing based on branch_type |
Maven jobs use machine executors with Docker pre-installed. Tests using Testcontainers, LocalStack, or other Docker-dependent frameworks work without additional configuration.
### Publish Job Parameters
### Required Context Variables
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `branch_type` | string | "snapshot" | Branch type: snapshot, release_candidate, release, hotfix |
| Variable | Purpose |
|----------|---------|
| `MAVEN_USERNAME` | Sonatype username |
| `MAVEN_PASSWORD` | Sonatype password |
| `GPG_PRIVATE_KEY_B64` | Base64-encoded GPG key |
| `GPG_KEYNAME` | GPG key ID |
| `GPG_PASSPHRASE` | GPG passphrase |
| `GITHUB_TOKEN` | GitHub API token |
## 🔧 Development
## Project Status
### Prerequisites
**Maturity:** Stable, used across all QQQ repositories
**Breaking changes:** See [CHANGELOG.md](CHANGELOG.md)
**Roadmap:**
- GitHub Actions support
- Parallel test execution
- Container image publishing
## Contributing
```bash
# Install CircleCI CLI
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | sudo bash
# Install linting tools (macOS)
brew install shellcheck yamllint
# Install linting tools (Ubuntu/Debian)
sudo apt-get install shellcheck yamllint
```
### Development Commands
```bash
# Core development
make pack # Pack orb (resolves <<include()>>)
make validate # Validate packed orb
make lint # Run all linting checks (YAML, ShellCheck, CircleCI orb)
make dev # Pack + validate + show status
make clean # Clean build artifacts and test data
# Testing
make test # Pack and validate orb
make test-scripts # Run comprehensive calculate_version.sh tests
make test-all # Run all tests (orb + scripts)
# Publishing (with full build cycle)
make publish-snapshot # Publish as kingsrook/qqq-orb@dev:snapshot
make publish-release # Publish as kingsrook/qqq-orb@X.Y.Z
```
### Quality Gates
All publishing commands enforce a complete quality gate:
1. **check-clean**: Ensures working directory is clean
2. **lint**: Runs all linting checks (YAML, ShellCheck, CircleCI orb validation)
3. **clean**: Removes all generated files for fresh build
4. **dev**: Development workflow (pack + validate)
5. **test-all**: Comprehensive testing (orb + scripts)
## 📋 Intelligent Version Management
Automated version calculation with GitFlow integration and feature branch support:
| Branch Pattern | Version Change | Example |
|----------------|----------------|---------|
| `develop` | Minor bump | `1.5.0-SNAPSHOT` → `1.6.0-SNAPSHOT` |
| `release/1.5` | RC versions | `1.5.0-RC.1`, `1.5.0-RC.2`, ... |
| `main` | Stable release | `1.5.0-RC.3` → `1.5.0` **requires v* tag** |
| `hotfix/1.5.1` | Patch bump | `1.5.0` → `1.5.1` |
| `feature/new-feature` | Feature-specific | `1.5.0-SNAPSHOT` → `1.5.0-NEW-abc1234-SNAPSHOT` |
### Feature Branch Versioning
Feature branches create unique, traceable versions:
- **Format**: `{version}-{ABBREV}-{commit_hash}-SNAPSHOT`
- **Example**: `feature/new-feature` → `1.5.0-NEW-abc1234-SNAPSHOT`
- **Dynamic Updates**: Automatically updates when commit hash changes
- **Safe Abbreviations**: 3-character uppercase feature name abbreviation
### Version Parsing Support
The version calculator handles multiple formats:
- **Standard**: `1.5.0`, `1.5.0-SNAPSHOT`, `1.5.0-RC.1`
- **V-prefixed**: `v1.5.0` → `1.5.0` (clean conversion)
- **Feature-specific**: `1.5.0-NEW-abc1234-SNAPSHOT`
**Main branch requires release tags**:
```bash
git tag -a v1.5.0 -m "Release 1.5.0"
git push origin v1.5.0
```
## 🧪 Comprehensive Testing
### Test Suite Features
- **Dynamic Test Environment**: Creates isolated git repositories for each test run
- **Pattern Matching**: Supports wildcard patterns for commit hash testing
- **Comprehensive Coverage**: Tests all branch types and edge cases
- **CI Integration**: Clean exit codes and minimal output for CI systems
- **Automatic Cleanup**: Test data removed automatically after tests
### Running Tests
```bash
# Run all tests
git clone git@github.com:QRun-IO/qqq-orb.git
cd qqq-orb
make test-all
# Run specific test suites
make test # Orb tests only
make test-scripts # Script tests only
# Run with verbose output
./tests/run_tests.sh --verbose
# Run in CI mode
./tests/run_tests.sh --ci
# Run linting checks
make lint
```
### Test Coverage
See [QQQ Contribution Guidelines](https://github.com/Kingsrook/qqq/blob/develop/CONTRIBUTING.md).
The orb includes comprehensive testing:
- **YAML Validation**: CircleCI orb configuration validation
- **Shell Script Testing**: ShellCheck for shell script validation
- **Orb Packing**: Tests orb packing and resolution
- **Version Calculation**: 20+ test cases covering all branch types
- **Integration Testing**: End-to-end workflow testing
- **Edge Case Testing**: Invalid formats, missing tags, error conditions
## License
## 📦 Usage Examples
### Maven Project (Backend Only)
```yaml
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: snapshot
```
### Node.js Project (Frontend Only)
```yaml
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: release
```
### Hybrid Project (Maven + Node.js)
```yaml
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: release_candidate
```
## 🤝 Contributing
**Important**: This repository is a component of the QQQ framework. All contributions, issues, and discussions should go through the main QQQ repository.
### Development Workflow
1. **Fork the main QQQ repository**: https://github.com/Kingsrook/qqq
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** (including orb changes if applicable)
4. **Run tests**: `make test-all`
5. **Run linting**: `make lint`
6. **Commit your changes**: `git commit -m 'Add amazing feature'`
7. **Push to the branch**: `git push origin feature/amazing-feature`
8. **Open a Pull Request** to the main QQQ repository
### Code Standards
- **YAML**: Follow CircleCI orb best practices
- **Shell Scripts**: Use ShellCheck for validation, comprehensive testing
- **Documentation**: Update README and inline documentation
- **Testing**: Comprehensive test coverage with dynamic test environments
- **Quality Gates**: All changes must pass linting and testing
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```
QQQ Orb
Copyright (C) 2021-2024 Kingsrook, LLC
651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
contact@kingsrook.com | https://github.com/Kingsrook/
```
## 🆘 Support & Community
### ⚠️ Important: Use Main QQQ Repository
**All support, issues, discussions, and community interactions should go through the main QQQ repository:**
- **Main Repository**: https://github.com/Kingsrook/qqq
- **Issues**: https://github.com/Kingsrook/qqq/issues
- **Discussions**: https://github.com/Kingsrook/qqq/discussions
- **Wiki**: https://github.com/Kingsrook/qqq/wiki
### Why This Repository Exists
This repository is maintained separately from the main QQQ repository to:
- **Enable independent orb development** and versioning
- **Allow orb-specific CI/CD** and deployment pipelines
- **Provide clear separation** between orb and framework concerns
- **Support different release cycles** for CI/CD tools vs. core framework
### Getting Help
- **Documentation**: Check the [QQQ Wiki](https://github.com/Kingsrook/qqq/wiki)
- **Issues**: Report bugs and feature requests on [Main QQQ Issues](https://github.com/Kingsrook/qqq/issues)
- **Discussions**: Join community discussions on [Main QQQ Discussions](https://github.com/Kingsrook/qqq/discussions)
- **Questions**: Ask questions in the main QQQ repository
### Contact Information
- **Company**: Kingsrook, LLC
- **Email**: contact@kingsrook.com
- **Website**: https://qrun.io
- **Main GitHub**: https://github.com/Kingsrook/qqq
- **CircleCI Registry**: [kingsrook/qqq-orb](https://circleci.com/developer/orbs/orb/kingsrook/qqq-orb)
## 🙏 Acknowledgments
- **CircleCI Team**: For the excellent CI/CD platform and orb system
- **Maven Team**: For the powerful Java build system
- **npm Team**: For the Node.js package management system
- **QQQ Framework Team**: For the underlying low-code platform
- **Open Source Community**: For the tools and libraries that make this possible
---
**Built with ❤️ by the Kingsrook Team**
**This is a CI/CD component of the QQQ framework. For complete information, support, and community, visit: https://github.com/Kingsrook/qqq**
AGPL-3.0 - QRun-IO
+3 -4
View File
@@ -4,14 +4,13 @@ version: 2.1
description: >
QQQ Orb to handle the branching, testing, releasing, and auto updating of
all maven and npm based projects within the Kingsrook/QRunIO Repo world.
all Maven and npm based projects within the QRun-IO ecosystem.
display:
home_url: "https://www.qrun.io"
source_url: "https://github.com/Kingsrook/qqq-orb"
home_url: "https://github.com/QRun-IO/qqq-orb"
source_url: "https://github.com/QRun-IO/qqq-orb"
orbs:
localstack: localstack/platform@2.1
browser-tools: circleci/browser-tools@1.4.7
slack: circleci/slack@5.2.1
node: circleci/node@4.7
@@ -0,0 +1,9 @@
description: >
Collects SpotBugs and PMD reports from all modules into a central
location for artifact storage. Generates a summary report.
steps:
- run:
name: Collect Static Analysis Reports
command: <<include(scripts/collect_static_analysis_reports.sh)>>
when: always
+6 -1
View File
@@ -11,6 +11,8 @@ steps:
- restore_cache:
keys:
- v1-dependencies-{{ checksum "pom.xml" }}
- restore_cache:
keys:
- v1-npm-dependencies-{{ checksum "package.json" }}
- run:
name: Setup NPM authentication
@@ -30,5 +32,8 @@ steps:
- save_cache:
paths:
- ~/.m2
- node_modules
key: v1-dependencies-{{ checksum "pom.xml" }}
- save_cache:
paths:
- node_modules
key: v1-npm-dependencies-{{ checksum "package.json" }}
+9
View File
@@ -33,6 +33,9 @@ steps:
- restore_cache:
keys:
- v1-dependencies-{{ checksum "pom.xml" }}
- restore_cache:
keys:
- v1-npm-dependencies-{{ checksum "package.json" }}
# (Optional) Guard: if node_modules is missing, install it quickly so "npm run build" works
- run:
@@ -67,3 +70,9 @@ steps:
paths:
- ~/.m2
key: v1-dependencies-{{ checksum "pom.xml" }}
# Re-cache Node deps
- save_cache:
paths:
- node_modules
key: v1-npm-dependencies-{{ checksum "package.json" }}
+12
View File
@@ -0,0 +1,12 @@
description: >
Full checkout of the repository with complete git history.
Uses CircleCI's checkout (handles SSH keys and known_hosts)
then fetches full history for version calculation.
steps:
- checkout
- run:
name: Fetch full git history
command: |
git fetch --unshallow || true
git fetch --tags || true
+10 -1
View File
@@ -2,7 +2,14 @@ description: >
Git operations for version management
- Adds SSH keys for Git operations
- Sets up Git identity for version commits
- Commits version changes if modified
- Commits version changes if modified (skipped for feature branches)
parameters:
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, hotfix, or feature"
steps:
- add_ssh_keys # injects the CircleCI User Key (write-capable)
- run:
@@ -10,4 +17,6 @@ steps:
command: <<include(scripts/manage_version_git_config.sh)>>
- run:
name: Commit version change if modified
environment:
BRANCH_TYPE: << parameters.branch_type >>
command: <<include(scripts/manage_version_commit.sh)>>
+30
View File
@@ -0,0 +1,30 @@
description: >
Installs Eclipse Temurin JDK and Maven on Ubuntu machine executor.
Sets JAVA_HOME and updates PATH for subsequent steps.
Optionally installs Node.js for frontend builds.
Also verifies Docker is available (required for Testcontainers/LocalStack tests).
parameters:
java_version:
type: string
default: "21"
description: >
Java major version to install (e.g., "17", "21").
Uses Eclipse Temurin (AdoptOpenJDK successor) distribution.
install_node:
type: boolean
default: false
description: "Whether to also install Node.js (for frontend builds)"
node_version:
type: string
default: "20"
description: "Node.js major version to install (e.g., '18', '20')"
steps:
- run:
name: Install Java << parameters.java_version >> and build tools
environment:
PARAM_JAVA_VERSION: << parameters.java_version >>
PARAM_INSTALL_NODE: << parameters.install_node >>
PARAM_NODE_VERSION: << parameters.node_version >>
command: <<include(scripts/install_java.sh)>>
+17
View File
@@ -0,0 +1,17 @@
description: >
Runs PMD static analysis on Maven project.
Detects code quality issues, potential bugs, and style violations.
Requires maven-pmd-plugin configured in project pom.xml.
parameters:
fail_on_violation:
type: boolean
default: false
description: "Fail the build if PMD finds violations"
steps:
- run:
name: Run PMD Analysis
environment:
PMD_FAIL_ON_VIOLATION: << parameters.fail_on_violation >>
command: <<include(scripts/mvn_pmd.sh)>>
+18
View File
@@ -0,0 +1,18 @@
description: >
Runs SpotBugs static analysis on Maven project.
Reports potential bugs including null pointer issues, resource leaks,
and security vulnerabilities (via FindSecBugs plugin).
Requires spotbugs-maven-plugin configured in project pom.xml.
parameters:
fail_on_error:
type: boolean
default: false
description: "Fail the build if SpotBugs finds bugs"
steps:
- run:
name: Run SpotBugs Analysis
environment:
SPOTBUGS_FAIL_ON_ERROR: << parameters.fail_on_error >>
command: <<include(scripts/mvn_spotbugs.sh)>>
+1 -1
View File
@@ -9,4 +9,4 @@ steps:
command: <<include(scripts/node_npm_auth.sh)>>
- run:
name: "Publish to NPM"
command: npm publish --access public
command: <<include(scripts/node_npm_publish.sh)>>
+26
View File
@@ -0,0 +1,26 @@
description: >
Creates a GitHub Release for the current version tag.
- Extracts version from pom.xml or package.json
- Verifies the Git tag exists
- Creates GitHub release with auto-generated notes
- Adds artifact links to Maven Central and/or npmjs
- Handles prerelease versions (RC, SNAPSHOT, alpha, beta)
parameters:
project_type:
type: enum
enum: [maven, node, both, auto]
default: auto
description: >
Project type for artifact link generation.
- maven: Link to Maven Central
- node: Link to npmjs
- both: Link to both registries
- auto: Auto-detect from project files
steps:
- run:
name: Create GitHub Release
command: <<include(scripts/create_github_release.sh)>>
environment:
PROJECT_TYPE: << parameters.project_type >>
+37 -21
View File
@@ -4,55 +4,71 @@ description: >
usage:
version: 2.1
orbs:
qqq-orb: kingsrook/qqq-orb@0.3.1
qqq-orb: kingsrook/qqq-orb@0.3.8
workflows:
# Test workflow for feature branches
test_only:
jobs:
- qqq-orb/mvn_test_only:
context: [ qqq-maven-registry-credentials ]
filters:
branches:
ignore: [develop, main, /release\/.*/, /hotfix\/.*/]
filters:
branches:
ignore: /(develop|main|release/.*|hotfix/.*|integration.*)/
tags:
only: []
# Snapshot deployment for develop branch
publish_snapshot:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: snapshot
filters:
branches:
only: [develop]
filters:
branches:
only:
- develop
publish_feature:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: feature
filters:
branches:
only:
- feature/.*
tags:
only: [ /publish.*/ ]
# Release candidate workflow
publish_release_candidate:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: release_candidate
filters:
branches:
only: [/release\/.*/]
filters:
branches:
only:
- /release\/.*/
# Production release workflow
publish_release:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: release
filters:
branches:
only: [main]
filters:
branches:
only: [ main ]
tags:
only: [ /v.*/ ]
# Hotfix release workflow
publish_hotfix_release:
jobs:
- qqq-orb/mvn_publish:
context: [ qqq-maven-registry-credentials ]
branch_type: hotfix
filters:
branches:
only: [/hotfix\/.*/]
filters:
branches:
only:
- /hotfix\/.*/
+18
View File
@@ -0,0 +1,18 @@
description: >
Java/OpenJDK machine executor with Docker support.
Uses Ubuntu 22.04 VM with Docker pre-installed.
Java is installed via the install_java command.
Required for tests that use Testcontainers or LocalStack Docker extensions.
parameters:
image:
default: ubuntu-2204:current
description: >
Ubuntu machine image tag. Use 'current' for latest or pin to specific
version like 'ubuntu-2204:2023.02.1' for reproducibility.
type: string
machine:
image: '<<parameters.image>>'
resource_class: large
+19 -6
View File
@@ -1,21 +1,34 @@
description: >
Unified publishing job for all branch types
Unified publishing job for all branch types with frontend
Handles version management, building, testing, and publishing based on branch type
Supports: snapshot, release_candidate, release, and hotfix workflows
Supports: snapshot, release_candidate, release, hotfix, and feature workflows
executor: localstack/default
executor: java
parameters:
java_version:
type: string
default: "21"
description: "Java major version to install (e.g., '17', '21')"
node_version:
type: string
default: "20"
description: "Node.js major version to install (e.g., '18', '20')"
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
description: "Branch type: snapshot, release_candidate, release, hotfix, or feature"
steps:
- checkout
- install_java:
java_version: << parameters.java_version >>
install_node: true
node_version: << parameters.node_version >>
- git_full_checkout
- mvn_manage_version
- frontend_build
- frontend_test
- frontend_package
- mvn_jar_deploy
- git_operations
- git_operations:
branch_type: << parameters.branch_type >>
+17 -3
View File
@@ -1,12 +1,26 @@
description: >
Complete test-only workflow for feature branches
Complete test-only workflow for feature branches with frontend
Runs build, test, API version check, and documentation generation
Used by: test_only workflow for feature branches
Triggers: Any push to branches NOT matching develop, main, release/*, hotfix/*
executor: localstack/default
executor: java
parameters:
java_version:
type: string
default: "21"
description: "Java major version to install (e.g., '17', '21')"
node_version:
type: string
default: "20"
description: "Node.js major version to install (e.g., '18', '20')"
steps:
- checkout
- install_java:
java_version: << parameters.java_version >>
install_node: true
node_version: << parameters.node_version >>
- git_full_checkout
- frontend_build
- frontend_test
+37 -5
View File
@@ -1,15 +1,19 @@
description: >
Unified publishing job for all branch types
Handles version management, building, testing, and publishing based on branch type
Supports: snapshot, release_candidate, release, and hotfix workflows
Supports: snapshot, release_candidate, release (tagged), feature (tagged) and hotfix workflows
executor: localstack/default
executor: java
parameters:
java_version:
type: string
default: "21"
description: "Java major version to install (e.g., '17', '21')"
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
description: "Branch type: snapshot, release_candidate, release, features, or hotfix"
check_middleware_api_versions:
type: boolean
default: false
@@ -20,19 +24,47 @@ parameters:
description: "Whether to publish AsciiDoc documentation"
steps:
- checkout
- install_java:
java_version: << parameters.java_version >>
- git_full_checkout
- mvn_build
- mvn_manage_version
- attach_workspace:
at: .
- mvn_verify
- when:
condition: << parameters.check_middleware_api_versions >>
steps:
- check_middleware_api_versions
- mvn_jar_deploy
- git_operations
- when:
condition:
not:
equal: [ "<< parameters.branch_type >>", "feature" ]
steps:
- git_operations:
branch_type: << parameters.branch_type >>
- when:
condition: << parameters.publish_asciidoc >>
steps:
- publish_asciidoc
# GitHub releases only for final releases and hotfixes (not RCs)
# RCs just publish artifacts - GitHub release happens when merged to main
- when:
condition:
or:
- equal: [ "<< parameters.branch_type >>", "release" ]
- equal: [ "<< parameters.branch_type >>", "hotfix" ]
steps:
- publish_github_release:
project_type: maven
+8 -2
View File
@@ -4,16 +4,22 @@ description: >
Used by: test_only workflow for feature branches
Triggers: Any push to branches NOT matching develop, main, release/*, hotfix/*
executor: localstack/default
executor: java
parameters:
java_version:
type: string
default: "21"
description: "Java major version to install (e.g., '17', '21')"
check_middleware_api_versions:
type: boolean
default: false
description: "Whether to run middleware API version checks"
steps:
- checkout
- install_java:
java_version: << parameters.java_version >>
- git_full_checkout
- mvn_build
- mvn_verify
- when:
+19 -2
View File
@@ -3,16 +3,22 @@ description: >
Handles version management, building, testing, and publishing based on branch type
Supports: snapshot, release_candidate, release, and hotfix workflows
executor: localstack/default
executor:
name: default
tag: << parameters.node_version >>
parameters:
node_version:
type: string
default: "lts"
description: "Node.js version tag (e.g., 'lts', '18.0', '20.0')."
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
steps:
- checkout
- git_full_checkout
- node_install_dependencies
- node_run_tests
- node_manage_version
@@ -20,3 +26,14 @@ steps:
at: .
- node_build_package
- node_publish
# GitHub releases only for final releases and hotfixes (not RCs)
# RCs just publish artifacts - GitHub release happens when merged to main
- when:
condition:
or:
- equal: [ "<< parameters.branch_type >>", "release" ]
- equal: [ "<< parameters.branch_type >>", "hotfix" ]
steps:
- publish_github_release:
project_type: node
+8 -2
View File
@@ -3,15 +3,21 @@ description: >
Handles testing based on branch type
Supports: snapshot, release_candidate, release, and hotfix workflows
executor: localstack/default
executor:
name: default
tag: << parameters.node_version >>
parameters:
node_version:
type: string
default: "lts"
description: "Node.js version tag (e.g., 'lts', '18.0', '20.0')."
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
steps:
- checkout
- git_full_checkout
- node_install_dependencies
- node_run_tests
+72
View File
@@ -0,0 +1,72 @@
description: >
Runs SpotBugs and PMD static analysis on a Maven project.
This job is designed to be used in an optional workflow triggered
by tag (static-analysis/*) or pipeline parameter.
Usage in consuming repo:
workflows:
static_analysis:
when:
or:
- matches:
pattern: "^static-analysis/.*"
value: << pipeline.git.tag >>
- equal: [true, << pipeline.parameters.run_static_analysis >>]
jobs:
- qqq-orb/static_analysis
executor: java
parameters:
java_version:
type: string
default: "21"
description: "Java major version to install"
fail_on_spotbugs:
type: boolean
default: false
description: "Fail the build if SpotBugs finds bugs"
fail_on_pmd:
type: boolean
default: false
description: "Fail the build if PMD finds violations"
run_spotbugs:
type: boolean
default: true
description: "Run SpotBugs analysis"
run_pmd:
type: boolean
default: true
description: "Run PMD analysis"
steps:
- install_java:
java_version: << parameters.java_version >>
- git_full_checkout
- run:
name: Setup Maven Settings
command: <<include(scripts/setup_maven_settings.sh)>>
- restore_cache:
keys:
- v1-dependencies-{{ checksum "pom.xml" }}
- run:
name: Build and Install for Analysis
command: <<include(scripts/mvn_install_for_analysis.sh)>>
- save_cache:
paths:
- ~/.m2
key: v1-dependencies-{{ checksum "pom.xml" }}
- when:
condition: << parameters.run_spotbugs >>
steps:
- mvn_spotbugs:
fail_on_error: << parameters.fail_on_spotbugs >>
- when:
condition: << parameters.run_pmd >>
steps:
- mvn_pmd:
fail_on_violation: << parameters.fail_on_pmd >>
- collect_static_analysis_reports
- store_artifacts:
path: /home/circleci/static-analysis-reports
destination: static-analysis
+40 -4
View File
@@ -29,10 +29,41 @@ if [[ "$1" == "--dry-run" ]]; then
echo "DRY RUN MODE - No changes will be made"
fi
################################################
## Function to find original feature branch ##
################################################
find_original_feature_branch() {
local original_branch=""
# Method 1: Look for remote branches containing this commit
echo "Method 1: Checking remote branches..." >&2
original_branch=$(git branch -r --contains HEAD 2>/dev/null | grep 'origin/feature/' | head -1 | sed 's/origin\///' | sed 's/^[[:space:]]*//' || echo "")
if [[ -n "$original_branch" ]]; then
echo "Found via remote branches: [$original_branch]" >&2
fi
# Return the result
if [[ "$original_branch" =~ ^feature/ ]]; then
echo "✅ Found original feature branch: [$original_branch]" >&2
echo "$original_branch"
else
echo "⚠️ Could not determine original feature branch, using generic name" >&2
echo "feature/publish"
fi
}
####################################
## Get current branch and version ##
####################################
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
# Try to get branch from CircleCI environment variable first (for CI environments)
# then fall back to git command (for local development)
if [[ -n "$CIRCLE_BRANCH" ]]; then
echo "Using branch from CircleCI environment: $CIRCLE_BRANCH"
CURRENT_BRANCH="$CIRCLE_BRANCH"
else
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
fi
CURRENT_VERSION=$(grep '<revision>' "$POM_FILE" | sed 's/.*<revision>//;s/<.*//')
# Check if we're on a tag (HEAD means we're on a tag)
@@ -50,6 +81,9 @@ if [[ "$CURRENT_BRANCH" == "HEAD" ]]; then
echo "This is a release candidate tag, treating as release branch"
CURRENT_BRANCH="release/${CURRENT_TAG#v}"
CURRENT_BRANCH="release/${CURRENT_BRANCH%-RC.*}"
elif [[ "$CURRENT_TAG" =~ ^publish- ]]; then
echo "This is a publish tag for feature branch, treating as feature branch"
CURRENT_BRANCH=$(find_original_feature_branch)
else
echo "Unknown tag format: $CURRENT_TAG"
CURRENT_BRANCH="unknown"
@@ -90,8 +124,9 @@ extract_version_parts() {
PATCH=${BASH_REMATCH[3]}
#############################################################
## Handle feature-specific versions like 1.5.0-NEW-abc1234-SNAPSHOT ##
## or 1.4.0-test-new-orb-825957d-SNAPSHOT ##
#############################################################
elif [[ "$version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)-[A-Z]{3}-[a-f0-9]{7}-SNAPSHOT$ ]]; then
elif [[ "$version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)-[a-zA-Z0-9-]+-[a-f0-9]+-SNAPSHOT$ ]]; then
MAJOR=${BASH_REMATCH[1]}
MINOR=${BASH_REMATCH[2]}
PATCH=${BASH_REMATCH[3]}
@@ -108,6 +143,7 @@ extract_version_parts() {
fi
}
#########################################
## Function to set version using Maven ##
#########################################
@@ -279,7 +315,7 @@ handle_feature_branch() {
# Create safe abbreviation (first 3 characters, uppercase)
local feature_abbrev
feature_abbrev=$(echo "$feature_name" | cut -c1-3 | tr '[:lower:]' '[:upper:]')
feature_abbrev=$(echo "$feature_name" | cut -c1-100 | tr '[:upper:]' '[:lower:]')
# Generate short commit hash
local commit_hash
@@ -404,4 +440,4 @@ main() {
#######################
## Run main function ##
#######################
main "$@"
main "$@"
@@ -0,0 +1,46 @@
#!/bin/bash
# Collect SpotBugs and PMD reports to a central location for artifacts
REPORT_DIR="/home/circleci/static-analysis-reports"
mkdir -p "$REPORT_DIR/spotbugs" "$REPORT_DIR/pmd"
echo "Collecting static analysis reports..."
# Collect SpotBugs reports
find . -name "spotbugsXml.xml" -exec sh -c '
MODULE=$(dirname "$1" | sed "s|^\./||;s|/target.*||" | tr "/" "_")
cp "$1" "'"$REPORT_DIR/spotbugs"'/${MODULE}_spotbugs.xml" 2>/dev/null || true
' _ {} \;
# Collect PMD reports
find . -name "pmd.xml" -exec sh -c '
MODULE=$(dirname "$1" | sed "s|^\./||;s|/target.*||" | tr "/" "_")
cp "$1" "'"$REPORT_DIR/pmd"'/${MODULE}_pmd.xml" 2>/dev/null || true
' _ {} \;
# Generate combined summary
{
echo "=== Static Analysis Report Summary ==="
echo "Generated: $(date)"
echo ""
echo "SpotBugs:"
} > "$REPORT_DIR/summary.txt"
find "$REPORT_DIR/spotbugs" -name "*.xml" 2>/dev/null | while read -r f; do
MODULE=$(basename "$f" _spotbugs.xml)
COUNT=$(grep -c "<BugInstance" "$f" 2>/dev/null || echo "0")
echo " $MODULE: $COUNT bugs" >> "$REPORT_DIR/summary.txt"
done
echo "" >> "$REPORT_DIR/summary.txt"
echo "PMD:" >> "$REPORT_DIR/summary.txt"
find "$REPORT_DIR/pmd" -name "*.xml" 2>/dev/null | while read -r f; do
MODULE=$(basename "$f" _pmd.xml)
COUNT=$(grep -c "<violation" "$f" 2>/dev/null || echo "0")
echo " $MODULE: $COUNT violations" >> "$REPORT_DIR/summary.txt"
done
cat "$REPORT_DIR/summary.txt"
echo ""
echo "Reports collected to: $REPORT_DIR"
+217 -48
View File
@@ -3,86 +3,255 @@
############################################################################
## create_github_release.sh
## GitHub Release Creation Script
##
##
## This script creates GitHub releases for production releases.
## The Git tag should already exist from the version management process.
## This script creates the corresponding GitHub release using the GitHub API.
##
## Process:
## 1. Extracts version from pom.xml revision field
## 2. Verifies the Git tag exists (should be created by version management)
## 3. Creates GitHub release using GitHub API (no gh CLI required)
## 4. Generates release notes from recent commits
## 1. Extracts version from pom.xml or package.json
## 2. Verifies the Git tag exists
## 3. Creates GitHub release using GitHub API with auto-generated notes
## 4. Adds artifact links to Maven Central and/or npmjs
##
## Usage: Called by CircleCI orb commands publish_release and publish_hotfix
## Environment Variables:
## GITHUB_TOKEN - Required: GitHub token with repo scope
## PROJECT_TYPE - Optional: maven, node, or both (default: auto-detect)
## DRY_RUN - Optional: Set to "true" to skip API calls
## CIRCLE_PROJECT_USERNAME - CircleCI: GitHub org/user
## CIRCLE_PROJECT_REPONAME - CircleCI: Repository name
##
## Usage: Called by CircleCI orb command publish_github_release
## Output: Creates GitHub release for the existing tag
############################################################################
set -e
##################################
## Extract version from pom.xml ##
##################################
VERSION=$(grep '<revision>' pom.xml | sed 's/.*<revision>//;s/<.*//')
###################
## Configuration ##
###################
DRY_RUN="${DRY_RUN:-false}"
REPO_OWNER="${CIRCLE_PROJECT_USERNAME:-}"
REPO_NAME="${CIRCLE_PROJECT_REPONAME:-}"
API_URL="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases"
############################
## Validate configuration ##
############################
if [[ -z "$GITHUB_TOKEN" ]]; then
echo "ERROR: GITHUB_TOKEN environment variable is not set"
exit 1
fi
if [[ -z "$REPO_OWNER" ]] || [[ -z "$REPO_NAME" ]]; then
echo "ERROR: CIRCLE_PROJECT_USERNAME and CIRCLE_PROJECT_REPONAME must be set"
exit 1
fi
echo "Repository: ${REPO_OWNER}/${REPO_NAME}"
###############################
## Extract version from file ##
###############################
VERSION=""
PROJECT_TYPE="${PROJECT_TYPE:-auto}"
# Auto-detect project type if not specified
if [[ "$PROJECT_TYPE" == "auto" ]]; then
if [[ -f "pom.xml" ]]; then
PROJECT_TYPE="maven"
elif [[ -f "package.json" ]]; then
PROJECT_TYPE="node"
else
echo "ERROR: Cannot detect project type. No pom.xml or package.json found."
exit 1
fi
fi
echo "Project type: $PROJECT_TYPE"
# Extract version based on project type
if [[ "$PROJECT_TYPE" == "maven" ]] || [[ "$PROJECT_TYPE" == "both" ]]; then
if [[ -f "pom.xml" ]]; then
VERSION=$(grep '<revision>' pom.xml | sed 's/.*<revision>//;s/<.*//' | head -1)
if [[ -z "$VERSION" ]]; then
# Fallback to version tag if revision not found
VERSION=$(grep -m1 '<version>' pom.xml | sed 's/.*<version>//;s/<.*//')
fi
fi
fi
if [[ -z "$VERSION" ]] && { [[ "$PROJECT_TYPE" == "node" ]] || [[ "$PROJECT_TYPE" == "both" ]]; }; then
if [[ -f "package.json" ]]; then
VERSION=$(jq -r '.version' package.json)
fi
fi
if [[ -z "$VERSION" ]]; then
echo "ERROR: Could not extract version from project files"
exit 1
fi
TAG_NAME="v$VERSION"
echo "Creating GitHub release for tag: $TAG_NAME"
echo "Version: $VERSION"
echo "Tag: $TAG_NAME"
#######################################
## Determine if this is a prerelease ##
#######################################
PRERELEASE="false"
if [[ "$VERSION" =~ -RC\.[0-9]+$ ]] || [[ "$VERSION" =~ -SNAPSHOT$ ]] || [[ "$VERSION" =~ -alpha ]] || [[ "$VERSION" =~ -beta ]]; then
PRERELEASE="true"
echo "This is a prerelease version"
fi
##########################################
## Verify the tag exists (should be created by version management) ##
## Verify the tag exists ##
##########################################
if ! git tag --list | grep -q "^$TAG_NAME$"; then
echo "ERROR: Tag $TAG_NAME does not exist"
echo "The tag should have been created by the version management process"
exit 1
# Also check for version- prefix format
ALT_TAG="version-$VERSION"
if git tag --list | grep -q "^$ALT_TAG$"; then
TAG_NAME="$ALT_TAG"
echo "Using alternate tag format: $TAG_NAME"
else
echo "ERROR: Tag $TAG_NAME does not exist"
echo "The tag should have been created by the version management process"
exit 1
fi
fi
echo "Tag $TAG_NAME exists, proceeding with GitHub release creation"
##########################################
## Generate release notes from commits ##
##########################################
echo "Generating release notes..."
################################
## Build artifact links ##
################################
ARTIFACT_SECTION=""
# Get the previous tag for comparison
PREVIOUS_TAG=$(git describe --tags --abbrev=0 --match="v*" HEAD~1 2>/dev/null || echo "")
# Maven Central links
if [[ "$PROJECT_TYPE" == "maven" ]] || [[ "$PROJECT_TYPE" == "both" ]]; then
if [[ -f "pom.xml" ]]; then
GROUP_ID=$(grep -m1 '<groupId>' pom.xml | sed 's/.*<groupId>//;s/<.*//')
ARTIFACT_ID=$(grep -m1 '<artifactId>' pom.xml | sed 's/.*<artifactId>//;s/<.*//')
if [[ -n "$PREVIOUS_TAG" ]]; then
echo "Comparing with previous release: $PREVIOUS_TAG"
RELEASE_NOTES=$(git log --pretty=format:"- %s" "$PREVIOUS_TAG"..HEAD | head -20)
else
echo "No previous tag found, using recent commits"
RELEASE_NOTES=$(git log --pretty=format:"- %s" -10)
if [[ -n "$GROUP_ID" ]] && [[ -n "$ARTIFACT_ID" ]]; then
MAVEN_URL="https://central.sonatype.com/artifact/${GROUP_ID}/${ARTIFACT_ID}/${VERSION}"
ARTIFACT_SECTION="### Artifacts
**Maven Central:**
- [${GROUP_ID}:${ARTIFACT_ID}:${VERSION}](${MAVEN_URL})"
echo "Maven artifact: ${GROUP_ID}:${ARTIFACT_ID}"
fi
fi
fi
# Create a more detailed release notes
FULL_NOTES="## Release $VERSION
# NPM links
if [[ "$PROJECT_TYPE" == "node" ]] || [[ "$PROJECT_TYPE" == "both" ]]; then
if [[ -f "package.json" ]]; then
NPM_PACKAGE=$(jq -r '.name' package.json)
### Changes
$RELEASE_NOTES
if [[ -n "$NPM_PACKAGE" ]] && [[ "$NPM_PACKAGE" != "null" ]]; then
NPM_URL="https://www.npmjs.com/package/${NPM_PACKAGE}/v/${VERSION}"
if [[ -n "$ARTIFACT_SECTION" ]]; then
ARTIFACT_SECTION="${ARTIFACT_SECTION}
### Artifacts
This release includes Maven artifacts published to Maven Central.
**NPM:**
- [${NPM_PACKAGE}@${VERSION}](${NPM_URL})"
else
ARTIFACT_SECTION="### Artifacts
**NPM:**
- [${NPM_PACKAGE}@${VERSION}](${NPM_URL})"
fi
echo "NPM package: ${NPM_PACKAGE}"
fi
fi
fi
# Add footer
if [[ -n "$ARTIFACT_SECTION" ]]; then
ARTIFACT_SECTION="${ARTIFACT_SECTION}
---
*Automated release from CircleCI*"
_Automated release via CircleCI_"
fi
###########################
## Create GitHub release ##
###########################
echo "Creating GitHub release for $TAG_NAME"
# Create the release using GitHub API
curl -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"tag_name\": \"$TAG_NAME\",
\"name\": \"Release $VERSION\",
\"body\": $(echo "$FULL_NOTES" | jq -Rs .),
\"draft\": false,
\"prerelease\": false
}" \
"https://api.github.com/repos/Kingsrook/qqq/releases"
if [[ "$DRY_RUN" == "true" ]]; then
echo "DRY RUN: Would create release with:"
echo " Tag: $TAG_NAME"
echo " Name: Release $VERSION"
echo " Prerelease: $PRERELEASE"
echo " Artifact section:"
echo "$ARTIFACT_SECTION"
echo "DRY RUN: Skipping API call"
exit 0
fi
echo "✅ GitHub release created successfully for $TAG_NAME"
# Build the request body
# Using generate_release_notes to auto-generate from PRs (respects .github/release.yml)
REQUEST_BODY=$(jq -n \
--arg tag "$TAG_NAME" \
--arg name "Release $VERSION" \
--arg body "$ARTIFACT_SECTION" \
--argjson prerelease "$PRERELEASE" \
'{
tag_name: $tag,
name: $name,
body: $body,
draft: false,
prerelease: $prerelease,
generate_release_notes: true
}')
# Create the release with retry logic
MAX_RETRIES=2
RETRY_COUNT=0
while [[ $RETRY_COUNT -lt $MAX_RETRIES ]]; do
HTTP_RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Content-Type: application/json" \
-d "$REQUEST_BODY" \
"$API_URL")
HTTP_BODY=$(echo "$HTTP_RESPONSE" | sed '$d')
HTTP_CODE=$(echo "$HTTP_RESPONSE" | tail -n1)
if [[ "$HTTP_CODE" -ge 200 ]] && [[ "$HTTP_CODE" -lt 300 ]]; then
RELEASE_URL=$(echo "$HTTP_BODY" | jq -r '.html_url')
echo "GitHub release created successfully: $RELEASE_URL"
exit 0
elif [[ "$HTTP_CODE" -ge 500 ]]; then
echo "Server error (HTTP $HTTP_CODE), retrying..."
RETRY_COUNT=$((RETRY_COUNT + 1))
sleep 2
elif [[ "$HTTP_CODE" == "422" ]]; then
# Check if release already exists
if echo "$HTTP_BODY" | grep -q "already_exists"; then
echo "Release for $TAG_NAME already exists, skipping"
exit 0
else
echo "ERROR: GitHub API returned HTTP $HTTP_CODE"
echo "$HTTP_BODY"
# Don't fail the build - artifacts are already published
echo "WARNING: GitHub release creation failed, but artifacts are published"
exit 0
fi
else
echo "ERROR: GitHub API returned HTTP $HTTP_CODE"
echo "$HTTP_BODY"
# Don't fail the build - artifacts are already published
echo "WARNING: GitHub release creation failed, but artifacts are published"
exit 0
fi
done
echo "WARNING: GitHub release creation failed after $MAX_RETRIES retries"
echo "Artifacts are published, continuing..."
exit 0
+14 -1
View File
@@ -3,7 +3,7 @@
############################################################################
## frontend_test_collect_results.sh
## Collect JUnit XML Test Results
##
##
## This script collects JUnit XML test results from the Maven
## surefire reports directory for CircleCI test reporting.
##
@@ -16,3 +16,16 @@ set -e
echo "Collecting JUnit XML test results"
mkdir -p ~/test-results/junit/
find . -type f -regex ".*/target/surefire-reports/.*xml" -exec cp {} ~/test-results/junit/ \; || true
############################################################################
## Strip rerunFailure elements that CircleCI's JUnit parser doesn't support
## These are added by Maven Surefire when rerunFailingTestsCount > 0
############################################################################
echo "Cleaning JUnit XML files for CircleCI compatibility"
for xml_file in ~/test-results/junit/*.xml; do
if [ -f "$xml_file" ]; then
sed -i.bak '/<rerunFailure/,/<\/rerunFailure>/d' "$xml_file" 2>/dev/null || \
sed -i '' '/<rerunFailure/,/<\/rerunFailure>/d' "$xml_file" 2>/dev/null || true
rm -f "${xml_file}.bak" 2>/dev/null || true
fi
done
+2 -1
View File
@@ -14,6 +14,7 @@
set -e
echo "Installing browser dependencies"
export DEBIAN_FRONTEND=noninteractive
sudo apt-get update
sudo apt-get install -y \
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
libnss3-dev libgdk-pixbuf2.0-dev libgtk-3-dev libxss-dev
+57
View File
@@ -0,0 +1,57 @@
#!/bin/bash
set -euo pipefail
# Install Java and Maven on Ubuntu machine executor
# Uses Eclipse Temurin (AdoptOpenJDK successor) for reliable JDK installation
# Optionally installs Node.js via NodeSource repository
JAVA_VERSION="${PARAM_JAVA_VERSION:-21}"
INSTALL_NODE="${PARAM_INSTALL_NODE:-false}"
NODE_VERSION="${PARAM_NODE_VERSION:-20}"
echo "Installing Java ${JAVA_VERSION} and Maven..."
# Add Eclipse Temurin repository
sudo apt-get update -qq
sudo apt-get install -y -qq wget apt-transport-https gpg maven curl
# Add Temurin GPG key
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
# Add repository
echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
# Install Java
sudo apt-get update -qq
sudo apt-get install -y -qq "temurin-${JAVA_VERSION}-jdk"
# Set JAVA_HOME
JAVA_HOME="/usr/lib/jvm/temurin-${JAVA_VERSION}-jdk-amd64"
echo "export JAVA_HOME=${JAVA_HOME}" >> "${BASH_ENV}"
echo "export PATH=${JAVA_HOME}/bin:\$PATH" >> "${BASH_ENV}"
# Install Node.js if requested
if [ "${INSTALL_NODE}" = "true" ]; then
echo ""
echo "Installing Node.js ${NODE_VERSION}..."
curl -fsSL "https://deb.nodesource.com/setup_${NODE_VERSION}.x" | sudo -E bash -
sudo apt-get install -y -qq nodejs
echo ""
echo "Node.js version:"
node --version
echo "npm version:"
npm --version
fi
# Verify installation
echo ""
echo "Java version:"
java -version
echo ""
echo "Maven version:"
mvn --version
echo ""
echo "Docker version:"
docker --version
echo ""
echo "Installation completed successfully"
+22 -4
View File
@@ -20,6 +20,16 @@
set -e
################################################################
## Skip version commit for feature branches ##
## Feature versions are ephemeral (include commit hash) and ##
## don't need to be persisted back to the repository ##
################################################################
if [[ "$BRANCH_TYPE" == "feature" ]]; then
echo "Skipping version commit for feature branch (ephemeral versions)"
exit 0
fi
################################################################
## Check if pom.xml was modified and commit changes if needed ##
################################################################
@@ -28,14 +38,22 @@ if [[ -n "$(git status --porcelain pom.xml)" ]]; then
git add pom.xml
git commit -m "Bump version to $NEW_VERSION [skip ci]"
# Determine target branch
if [ -n "$CIRCLE_BRANCH" ]; then
git push origin "HEAD:${CIRCLE_BRANCH}"
TARGET_BRANCH="$CIRCLE_BRANCH"
else
# Tag build: push to main (or your default branch)
git push origin HEAD:main
TARGET_BRANCH="main"
fi
echo "Version updated to: $NEW_VERSION and pushed"
# Try to push, but don't fail the build if push fails
# This can happen if another build pushed first (race condition)
if git push origin "HEAD:${TARGET_BRANCH}"; then
echo "Version updated to: $NEW_VERSION and pushed to ${TARGET_BRANCH}"
else
echo "WARNING: Failed to push version commit to ${TARGET_BRANCH}"
echo "This is not fatal - version will be updated on next build"
echo "Common causes: concurrent builds, branch protection rules"
fi
else
echo "No version change needed"
fi
+6
View File
@@ -0,0 +1,6 @@
#!/bin/bash
set -e
echo "Building and installing project for static analysis..."
mvn install -DskipTests -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true
echo "Build complete - artifacts installed to local repository"
+23
View File
@@ -0,0 +1,23 @@
#!/bin/bash
set -e
echo "Running PMD static analysis..."
# Default to report-only mode unless PMD_FAIL_ON_VIOLATION is set
FAIL_FLAG=""
if [ "${PMD_FAIL_ON_VIOLATION}" = "true" ]; then
FAIL_FLAG="-Dpmd.failOnViolation=true"
fi
# Run PMD
mvn pmd:check -DskipTests ${FAIL_FLAG} 2>&1 | tee /tmp/pmd-output.txt
# Summarize results
echo ""
echo "=== PMD Summary ==="
find . -name "pmd.xml" -exec sh -c '
MODULE=$(dirname "$1" | sed "s|^\./||;s|/target.*||")
COUNT=$(grep -c "<violation" "$1" 2>/dev/null || echo "0")
echo " $MODULE: $COUNT violations"
' _ {} \; 2>/dev/null | sort || true
echo "==================="
+23
View File
@@ -0,0 +1,23 @@
#!/bin/bash
set -e
echo "Running SpotBugs static analysis..."
# Default to report-only mode unless SPOTBUGS_FAIL_ON_ERROR is set
FAIL_FLAG=""
if [ "${SPOTBUGS_FAIL_ON_ERROR}" = "true" ]; then
FAIL_FLAG="-Dspotbugs.failOnError=true"
fi
# Run SpotBugs
mvn spotbugs:check -DskipTests ${FAIL_FLAG} 2>&1 | tee /tmp/spotbugs-output.txt
# Summarize results
echo ""
echo "=== SpotBugs Summary ==="
find . -name "spotbugsXml.xml" -exec sh -c '
MODULE=$(dirname "$1" | sed "s|^\./||;s|/target.*||")
COUNT=$(grep -c "<BugInstance" "$1" 2>/dev/null || echo "0")
echo " $MODULE: $COUNT bugs"
' _ {} \; 2>/dev/null | sort || true
echo "========================"
+44
View File
@@ -0,0 +1,44 @@
#!/bin/bash
############################################################################
## node_npm_publish.sh
## NPM Publishing Script with Prerelease Tag Support
##
## This script publishes npm packages with proper handling of prerelease
## versions. NPM requires a --tag flag for prerelease versions.
##
## Prerelease detection:
## - RC versions (e.g., 1.0.0-RC.1) -> --tag rc
## - SNAPSHOT versions (e.g., 1.0.0-SNAPSHOT) -> --tag snapshot
## - Alpha/Beta versions -> --tag next
## - Stable versions (e.g., 1.0.0) -> --tag latest (default)
##
## Usage: Called by CircleCI orb command node_publish
############################################################################
set -e
# Extract version from package.json
VERSION=$(grep '"version"' package.json | sed 's/.*"version": "//;s/".*//')
echo "Publishing version: $VERSION"
# Determine the appropriate npm tag based on version
if [[ "$VERSION" =~ -RC\.[0-9]+$ ]]; then
NPM_TAG="rc"
echo "Detected RC version - using tag: $NPM_TAG"
elif [[ "$VERSION" =~ -SNAPSHOT$ ]]; then
NPM_TAG="snapshot"
echo "Detected SNAPSHOT version - using tag: $NPM_TAG"
elif [[ "$VERSION" =~ -(alpha|beta) ]]; then
NPM_TAG="next"
echo "Detected alpha/beta version - using tag: $NPM_TAG"
else
NPM_TAG="latest"
echo "Detected stable version - using tag: $NPM_TAG"
fi
# Publish with the appropriate tag
echo "Running: npm publish --access public --tag $NPM_TAG"
npm publish --access public --tag "$NPM_TAG"
echo "Successfully published $VERSION with tag $NPM_TAG"
+24 -15
View File
@@ -1,15 +1,14 @@
#!/bin/bash
############################################################################
## run_tests.sh
## Test runner for calculate_version.sh script
##
## This script runs the comprehensive test suite and provides
## different output formats for different use cases.
##
## Usage: ./run_tests.sh [--verbose] [--ci]
############################################################################
################################################################
## run_tests.sh ##
## Test runner for calculate_version.sh script ##
## ##
## This script runs the comprehensive test suite and provides ##
## different output formats for different use cases. ##
## ##
## Usage: ./run_tests.sh [--verbose] [--ci] ##
################################################################
set -e
###################
@@ -48,20 +47,26 @@ done
main() {
echo "🧪 Running calculate_version.sh test suite..."
# Verify test script exists
###############################
## Verify test script exists ##
###############################
if [[ ! -f "$TEST_SCRIPT" ]]; then
echo "❌ Test script not found: $TEST_SCRIPT"
exit 1
fi
# Run tests
###############
## Run tests ##
###############
local test_args=""
if [[ "$VERBOSE" == "true" ]]; then
test_args="--verbose"
fi
if [[ "$CI_MODE" == "true" ]]; then
# CI mode: minimal output, focus on results
###############################################
## CI mode: minimal output, focus on results ##
###############################################
echo "Running tests in CI mode..."
if "$TEST_SCRIPT" $test_args > /tmp/test_output.log 2>&1; then
echo "✅ All tests passed!"
@@ -73,10 +78,14 @@ main() {
exit 1
fi
else
# Interactive mode: full output
###################################
## Interactive mode: full output ##
###################################
"$TEST_SCRIPT" $test_args
fi
}
# Run main function
#######################
## Run main function ##
#######################
main "$@"
+235 -75
View File
@@ -1,15 +1,14 @@
#!/bin/bash
############################################################################
## test_calculate_version.sh
## Comprehensive test suite for calculate_version.sh script
##
## This test suite validates all branch types and edge cases for the
## version calculation script.
##
## Usage: ./test_calculate_version.sh [--verbose]
############################################################################
#######################################################################
## test_calculate_version.sh ##
## Comprehensive test suite for calculate_version.sh script ##
## ##
## This test suite validates all branch types and edge cases for the ##
## version calculation script. ##
## ##
## Usage: ./test_calculate_version.sh [--verbose] ##
#######################################################################
set -e
###################
@@ -21,7 +20,9 @@ CALCULATE_VERSION_SCRIPT="$PROJECT_ROOT/src/scripts/calculate_version.sh"
TEST_DIR="$PROJECT_ROOT/tests/test_data"
VERBOSE=false
# Test counters
###################
## Test counters ##
###################
TESTS_RUN=0
TESTS_PASSED=0
TESTS_FAILED=0
@@ -33,23 +34,31 @@ if [[ "$1" == "--verbose" ]]; then
VERBOSE=true
fi
####################################
## Test Framework Functions ##
####################################
##############################
## Test Framework Functions ##
##############################
# Create a temporary directory for test data
################################################
## Create a temporary directory for test data ##
################################################
setup_test_environment() {
echo "Setting up test environment..."
# Remove existing test directory if it exists
#################################################
## Remove existing test directory if it exists ##
#################################################
if [[ -d "$TEST_DIR" ]]; then
rm -rf "$TEST_DIR"
fi
# Create fresh test directory
#################################
## Create fresh test directory ##
#################################
mkdir -p "$TEST_DIR"
# Create a test git repository
##################################
## Create a test git repository ##
##################################
cd "$TEST_DIR"
git init --quiet
git config user.name "Test User"
@@ -58,7 +67,9 @@ setup_test_environment() {
echo "✅ Test environment ready"
}
# Clean up test environment
###############################
## Clean up test environment ##
###############################
cleanup_test_environment() {
echo "Cleaning up test environment..."
cd "$PROJECT_ROOT"
@@ -66,7 +77,9 @@ cleanup_test_environment() {
echo "✅ Cleanup complete"
}
# Create a test pom.xml file
################################
## Create a test pom.xml file ##
################################
create_test_pom() {
local version="$1"
cat > "$TEST_DIR/pom.xml" << EOF
@@ -87,30 +100,48 @@ create_test_pom() {
EOF
}
# Create a test branch
##########################
## Create a test branch ##
##########################
create_test_branch() {
local branch_name="$1"
local tag_name="$2"
cd "$TEST_DIR"
# Create and checkout branch
git checkout -b "$branch_name" 2>/dev/null || git checkout "$branch_name" 2>/dev/null || true
# Create a commit if needed
###############################
## Create a commit if needed ##
###############################
if [[ -z "$(git log --oneline 2>/dev/null)" ]]; then
echo "Initial commit" > README.md
git add README.md
git commit -m "Initial commit" --quiet
fi
# Create tag if specified
#############################
## Create tag if specified ##
#############################
if [[ -n "$tag_name" ]]; then
git tag -a "$tag_name" -m "Test tag $tag_name" 2>/dev/null || true
fi
################################
## Handle special HEAD case ##
################################
if [[ "$branch_name" == "HEAD" ]]; then
# For HEAD case, checkout the tag to simulate detached HEAD state
if [[ -n "$tag_name" ]]; then
git checkout "$tag_name" --quiet
fi
else
# Create and checkout branch
git checkout -b "$branch_name" 2>/dev/null || git checkout "$branch_name" 2>/dev/null || true
fi
}
# Run a test case
#####################
## Run a test case ##
#####################
run_test() {
local test_name="$1"
local branch_name="$2"
@@ -122,11 +153,15 @@ run_test() {
echo "🧪 Test: $test_name"
# Setup test case
#####################
## Setup test case ##
#####################
create_test_pom "$current_version"
create_test_branch "$branch_name" "$tag_name"
# Run the script
####################
## Run the script ##
####################
cd "$TEST_DIR"
local output
local exit_code=0
@@ -137,7 +172,9 @@ run_test() {
output=$(cd "$TEST_DIR" && POM_FILE=pom.xml "$CALCULATE_VERSION_SCRIPT" --dry-run 2>&1) || exit_code=$?
# Check if script ran successfully
######################################
## Check if script ran successfully ##
######################################
if [[ $exit_code -ne 0 ]]; then
echo " ❌ FAILED: Script exited with code $exit_code"
echo " Output: $output"
@@ -145,16 +182,32 @@ run_test() {
return 1
fi
# Extract the calculated version from output
################################################
## Extract the calculated version from output ##
################################################
local calculated_version
calculated_version=$(echo "$output" | grep "Calculated next version:" | sed 's/.*: //')
# Check if expected version contains wildcard pattern
#########################################################
## Check if expected version contains wildcard pattern ##
#########################################################
if [[ "$expected_version" == *"*"* ]]; then
# Convert wildcard pattern to regex
#######################################
## Convert wildcard pattern to regex ##
#######################################
local regex_pattern
# shellcheck disable=SC2001
regex_pattern=$(echo "$expected_version" | sed 's/\*/[a-f0-9]{7}/g')
# Handle different wildcard patterns:
# *-*-SNAPSHOT -> feature-name-commit-SNAPSHOT
# *-SNAPSHOT -> commit-SNAPSHOT
if [[ "$expected_version" == *-*-SNAPSHOT ]]; then
# Pattern: 1.4.0-*-*-SNAPSHOT -> 1.4.0-[feature-name]-[commit]-SNAPSHOT
regex_pattern=$(echo "$expected_version" | sed 's/\*/[a-zA-Z0-9-]+/g')
else
# Pattern: 1.4.0-*-SNAPSHOT -> 1.4.0-[commit]-SNAPSHOT
regex_pattern=$(echo "$expected_version" | sed 's/\*/[a-f0-9]+/g')
fi
if [[ "$calculated_version" =~ ^$regex_pattern$ ]]; then
echo " ✅ PASSED: Expected pattern $expected_version, got $calculated_version"
@@ -173,7 +226,9 @@ run_test() {
return 1
fi
else
# Exact match
#################
## Exact match ##
#################
if [[ "$calculated_version" == "$expected_version" ]]; then
echo " ✅ PASSED: Expected $expected_version, got $calculated_version"
TESTS_PASSED=$((TESTS_PASSED + 1))
@@ -193,7 +248,9 @@ run_test() {
fi
}
# Print test summary
########################
## Print test summary ##
########################
print_summary() {
echo ""
echo "=== Test Summary ==="
@@ -210,94 +267,176 @@ print_summary() {
fi
}
####################################
## Test Cases ##
####################################
################
## Test Cases ##
################
# Test main branch scenarios
################################
## Test main branch scenarios ##
################################
test_main_branch() {
echo ""
echo "=== Testing MAIN Branch ==="
# Test 1: Main branch with matching tag
###########################################
## Test 1: Main branch with matching tag ##
###########################################
run_test "Main branch with matching tag" "main" "1.5.0" "1.5.0" "v1.5.0"
# Test 2: Main branch with RC version and tag
#################################################
## Test 2: Main branch with RC version and tag ##
#################################################
run_test "Main branch with RC version" "main" "1.5.0-RC.1" "1.5.0" "v1.5.0"
# Test 3: Main branch with SNAPSHOT version and tag
#######################################################
## Test 3: Main branch with SNAPSHOT version and tag ##
#######################################################
run_test "Main branch with SNAPSHOT version" "main" "1.5.0-SNAPSHOT" "1.5.0" "v1.5.0"
# Test 4: Main branch on tag (HEAD state)
#############################################
## Test 4: Main branch on tag (HEAD state) ##
#############################################
run_test "Main branch on tag (HEAD)" "HEAD" "1.5.0" "1.5.0" "v1.5.0"
# Test 5: Main branch with v-prefixed version in pom.xml
############################################################
## Test 5: Main branch with v-prefixed version in pom.xml ##
############################################################
run_test "Main branch with v-prefixed version" "main" "v0.2.1" "0.2.1" "v0.2.1"
}
# Test develop branch scenarios
###################################
## Test develop branch scenarios ##
###################################
test_develop_branch() {
echo ""
echo "=== Testing DEVELOP Branch ==="
# Test 1: Develop branch with SNAPSHOT version (no recent activity)
#######################################################################
## Test 1: Develop branch with SNAPSHOT version (no recent activity) ##
#######################################################################
run_test "Develop branch - no recent activity" "develop" "1.5.0-SNAPSHOT" "1.5.0-SNAPSHOT" ""
# Test 2: Develop branch with RC version (should bump)
##########################################################
## Test 2: Develop branch with RC version (should bump) ##
##########################################################
run_test "Develop branch with RC version" "develop" "1.5.0-RC.1" "1.6.0-SNAPSHOT" ""
# Test 3: Develop branch with stable version (should bump)
##############################################################
## Test 3: Develop branch with stable version (should bump) ##
##############################################################
run_test "Develop branch with stable version" "develop" "1.5.0" "1.6.0-SNAPSHOT" ""
}
# Test release branch scenarios
###################################
## Test release branch scenarios ##
###################################
test_release_branch() {
echo ""
echo "=== Testing RELEASE Branch ==="
# Test 1: Release branch - first RC
#######################################
## Test 1: Release branch - first RC ##
#######################################
run_test "Release branch - first RC" "release/1.5" "1.5.0-SNAPSHOT" "1.5.0-RC.1" ""
# Test 2: Release branch - increment RC
###########################################
## Test 2: Release branch - increment RC ##
###########################################
run_test "Release branch - increment RC" "release/1.5" "1.5.0-RC.1" "1.5.0-RC.2" ""
# Test 3: Release branch - increment RC from RC.5
#####################################################
## Test 3: Release branch - increment RC from RC.5 ##
#####################################################
run_test "Release branch - increment RC.5" "release/1.5" "1.5.0-RC.5" "1.5.0-RC.6" ""
}
# Test hotfix branch scenarios
##################################
## Test hotfix branch scenarios ##
##################################
test_hotfix_branch() {
echo ""
echo "=== Testing HOTFIX Branch ==="
# Test 1: Hotfix branch - bump patch
########################################
## Test 1: Hotfix branch - bump patch ##
########################################
run_test "Hotfix branch - bump patch" "hotfix/fix-bug" "1.5.0" "1.5.1" ""
# Test 2: Hotfix branch - bump patch from RC
################################################
## Test 2: Hotfix branch - bump patch from RC ##
################################################
run_test "Hotfix branch - bump patch from RC" "hotfix/fix-bug" "1.5.0-RC.1" "1.5.1" ""
}
# Test feature branch scenarios
###################################
## Test feature branch scenarios ##
###################################
test_feature_branch() {
echo ""
echo "=== Testing FEATURE Branch ==="
# Test 1: Feature branch - convert SNAPSHOT to feature-specific version
run_test "Feature branch - convert SNAPSHOT to feature-specific version" "feature/new-feature" "1.5.0-SNAPSHOT" "1.5.0-NEW-*-SNAPSHOT" ""
###########################################################################
## Test 1: Feature branch - convert SNAPSHOT to feature-specific version ##
###########################################################################
run_test "Feature branch - convert SNAPSHOT to feature-specific version" "feature/new-feature" "1.5.0-SNAPSHOT" "1.5.0-new-feature-*-SNAPSHOT" ""
# Test 2: Feature branch - convert stable version to feature-specific SNAPSHOT
run_test "Feature branch - convert stable version to feature-specific SNAPSHOT" "feature/user-auth" "1.5.0" "1.5.0-USE-*-SNAPSHOT" ""
##################################################################################
## Test 2: Feature branch - convert stable version to feature-specific SNAPSHOT ##
##################################################################################
run_test "Feature branch - convert stable version to feature-specific SNAPSHOT" "feature/user-auth" "1.5.0" "1.5.0-user-auth-*-SNAPSHOT" ""
# Test 3: Feature branch - update existing feature-specific version with new commit hash
run_test "Feature branch - update existing feature-specific version" "feature/existing-feature" "1.5.0-EXI-abc1234-SNAPSHOT" "1.5.0-EXI-*-SNAPSHOT" ""
############################################################################################
## Test 3: Feature branch - update existing feature-specific version with new commit hash ##
############################################################################################
run_test "Feature branch - update existing feature-specific version" "feature/existing-feature" "1.5.0-SNAPSHOT" "1.5.0-existing-feature-*-SNAPSHOT" ""
############################################################################################
## Test 4: Feature branch - parse existing long feature-specific version ##
############################################################################################
run_test "Feature branch - parse existing long feature-specific version" "feature/test-new-orb" "1.4.0-test-new-orb-825957d-SNAPSHOT" "1.4.0-test-new-orb-*-SNAPSHOT" ""
}
# Test edge cases
####################################
## Test publish tag scenarios ##
####################################
test_publish_tag() {
echo ""
echo "=== Testing PUBLISH Tag Scenarios ==="
###########################################################################
## Test 1: Publish tag - convert SNAPSHOT to feature-specific version ##
## Note: Will use actual feature branch name found in git log ##
###########################################################################
run_test "Publish tag - convert SNAPSHOT to feature-specific version" "HEAD" "1.4.0-SNAPSHOT" "1.4.0-*-*-SNAPSHOT" "publish-825957d"
##################################################################################
## Test 2: Publish tag - convert stable version to feature-specific SNAPSHOT ##
## Note: Will use actual feature branch name found in git log ##
##################################################################################
run_test "Publish tag - convert stable version to feature-specific SNAPSHOT" "HEAD" "1.4.0" "1.4.0-*-*-SNAPSHOT" "publish-abc1234"
############################################################################################
## Test 3: Publish tag - update existing feature-specific version with new commit hash ##
############################################################################################
run_test "Publish tag - update existing feature-specific version" "HEAD" "1.4.0-test-feature-1234567-SNAPSHOT" "1.4.0-test-feature-*-SNAPSHOT" "publish-def5678"
############################################################################################
## Test 4: Publish tag with different commit hash format ##
## Note: Will use actual feature branch name found in git log ##
############################################################################################
run_test "Publish tag - different commit hash format" "HEAD" "1.5.0-SNAPSHOT" "1.5.0-*-*-SNAPSHOT" "publish-9a8b7c6"
}
#####################
## Test edge cases ##
#####################
test_edge_cases() {
echo ""
echo "=== Testing Edge Cases ==="
# Test 1: Invalid release branch format (should fail)
#########################################################
## Test 1: Invalid release branch format (should fail) ##
#########################################################
echo "🧪 Test: Invalid release branch format (should fail)"
TESTS_RUN=$((TESTS_RUN + 1))
@@ -318,10 +457,14 @@ test_edge_cases() {
TESTS_FAILED=$((TESTS_FAILED + 1))
fi
# Test 2: Unknown branch type
#################################
## Test 2: Unknown branch type ##
#################################
run_test "Unknown branch type" "unknown-branch" "1.5.0-SNAPSHOT" "1.5.0-SNAPSHOT" ""
# Test 3: Main branch with no tags (should fail)
####################################################
## Test 3: Main branch with no tags (should fail) ##
####################################################
echo "🧪 Test: Main branch with no tags (should fail)"
TESTS_RUN=$((TESTS_RUN + 1))
@@ -340,12 +483,16 @@ test_edge_cases() {
fi
}
# Test version parsing
##########################
## Test version parsing ##
##########################
test_version_parsing() {
echo ""
echo "=== Testing Version Parsing ==="
# Test various version formats
##################################
## Test various version formats ##
##################################
local test_versions=(
"1.0.0"
"1.0.0-SNAPSHOT"
@@ -363,7 +510,9 @@ test_version_parsing() {
for version in "${test_versions[@]}"; do
echo "🧪 Testing version parsing: $version"
# Create a simple test to verify version parsing doesn't crash
##################################################################
## Create a simple test to verify version parsing doesn't crash ##
##################################################################
create_test_pom "$version"
create_test_branch "main" ""
@@ -394,28 +543,39 @@ main() {
echo "Testing script: $CALCULATE_VERSION_SCRIPT"
echo ""
# Verify script exists
##########################
## Verify script exists ##
##########################
if [[ ! -f "$CALCULATE_VERSION_SCRIPT" ]]; then
echo "❌ Script not found: $CALCULATE_VERSION_SCRIPT"
exit 1
fi
# Setup test environment
############################
## Setup test environment ##
############################
setup_test_environment
# Run all test suites
#########################
## Run all test suites ##
#########################
test_main_branch
test_develop_branch
test_release_branch
test_hotfix_branch
test_feature_branch
test_publish_tag
test_edge_cases
test_version_parsing
# Cleanup and show results
##############################
## Cleanup and show results ##
##############################
cleanup_test_environment
print_summary
}
# Run main function
#######################
## Run main function ##
#######################
main "$@"