Compare commits

...
16 Commits
Author SHA1 Message Date
james.maes c0365111f5 fix: Updated git commit on main to work for tag releases for production releases 2025-09-16 10:50:57 -05:00
james.maes 002b82d1f1 fix: updated standard GH docs to point to top level project docs 2025-09-15 15:25:43 -05:00
james.maes 9751567138 fix: removed condistionals around git ops after version checks for main and hotfixes 2025-09-15 14:36:50 -05:00
james.maes 0383e9fabf feat: made publish_asciidoc a params run 2025-09-15 13:29:30 -05:00
james.maes 3ec32dd942 chore(github): added base level repo files and updated readme 2025-09-15 13:11:22 -05:00
james.maes daa7201398 fix: updated check_middleware_api_versions to be ran based on a param 2025-09-15 12:59:45 -05:00
james.maes 46556a1633 fix: version bump 2025-09-15 09:30:09 -05:00
james.maes 3c2087a0e2 fixed: bad syn rc update 2025-09-15 09:29:34 -05:00
james.maes 732a2a86b0 fix: Updated exmaple version 2025-09-15 09:24:43 -05:00
james.maes c5befd275a fix: reverted to only handle pom, npm is handled within its own job for now 2025-09-15 09:17:32 -05:00
james.maes 6ba26b4072 fix: adjusted default execution state for scripts 2025-09-15 09:14:42 -05:00
james.maes e3b087062c fix: converted longer commands to scripts per org linting 2025-09-15 09:13:29 -05:00
james.maes 8e2be0f286 fix: converted longer commands to scripts per org linting 2025-09-15 09:05:37 -05:00
james.maes 78448438b6 feat: Added support for pure node project 2025-09-15 08:54:42 -05:00
james.maes e0ecef9746 chore(make): Added support for publishing snapshots and tags 2025-09-15 08:34:31 -05:00
james.maes 7b408dc138 chore(make): Added support for publishing snapshots and tags 2025-09-15 08:33:29 -05:00
39 changed files with 912 additions and 114 deletions

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
---
name: Bug Report
about: Create a report to help us improve QQQ Orb
title: '[BUG] '
labels: ['bug', 'needs-triage']
assignees: ''
---
## 🐛 Bug Description
A clear and concise description of what the bug is.
## 🔄 Steps to Reproduce
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## ✅ Expected Behavior
A clear and concise description of what you expected to happen.
## ❌ Actual Behavior
A clear and concise description of what actually happened.
## 📸 Screenshots
If applicable, add screenshots to help explain your problem.
## 🖥️ Environment
- **QQQ Orb Version**: [e.g. 2.1.0]
- **CircleCI Version**: [e.g. 2.1]
- **Operating System**: [e.g. macOS, Ubuntu, Windows]
- **Project Type**: [e.g. Maven, Node.js, Hybrid]
## 📋 Additional Context
Add any other context about the problem here.
## 🔗 Related Issues
Link any related issues or discussions.
---
**Note**: This repository is a component of the QQQ framework. For general QQQ issues, please use the [main QQQ repository](https://github.com/Kingsrook/qqq/issues).
+11
View File
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: QQQ Framework Support
url: https://github.com/Kingsrook/qqq/issues
about: For general QQQ framework issues, please use the main QQQ repository
- name: QQQ Community Discussions
url: https://github.com/Kingsrook/qqq/discussions
about: Join community discussions and ask questions
- name: QQQ Documentation
url: https://github.com/Kingsrook/qqq/wiki
about: Check the QQQ Wiki for comprehensive documentation
+55
View File
@@ -0,0 +1,55 @@
---
name: Feature Request
about: Suggest an idea for QQQ Orb
title: '[FEATURE] '
labels: ['enhancement', 'needs-triage']
assignees: ''
---
## 🚀 Feature Description
A clear and concise description of the feature you'd like to see implemented.
## 💡 Motivation
Why is this feature needed? What problem does it solve?
## 📋 Detailed Description
A detailed description of the feature, including:
- **What**: What should the feature do?
- **Why**: Why is this feature important?
- **How**: How should it work?
- **When**: When would this be used?
## 🎯 Use Cases
Describe specific use cases for this feature:
1. **Use Case 1**: Description
2. **Use Case 2**: Description
3. **Use Case 3**: Description
## 🔧 Implementation Ideas
If you have ideas about how this could be implemented, please share them here.
## 📊 Priority
- [ ] Low - Nice to have
- [ ] Medium - Would be helpful
- [ ] High - Important for workflow
- [ ] Critical - Blocking current work
## 🔗 Related Issues
Link any related issues or discussions.
## 📝 Additional Context
Add any other context, mockups, or examples about the feature request here.
---
**Note**: This repository is a component of the QQQ framework. For general QQQ features, please use the [main QQQ repository](https://github.com/Kingsrook/qqq/issues).
+66
View File
@@ -0,0 +1,66 @@
## 📋 Description
Brief description of the changes in this PR.
## 🔗 Related Issue
Closes #(issue number)
## 🧪 Testing
- [ ] I have tested these changes locally
- [ ] I have run `make test` and all tests pass
- [ ] I have run `make lint` and all linting checks pass
- [ ] I have validated the orb configuration with `make validate`
## 📝 Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)
- [ ] Performance improvement
- [ ] Other (please describe):
## 🔍 Changes Made
- [ ] Updated orb configuration
- [ ] Added new commands or jobs
- [ ] Updated shell scripts
- [ ] Updated documentation
- [ ] Updated examples
- [ ] Other (please describe):
## 📸 Screenshots
If applicable, add screenshots to help explain your changes.
## 🖥️ Environment
- **QQQ Orb Version**: [e.g. 2.1.0]
- **CircleCI Version**: [e.g. 2.1]
- **Operating System**: [e.g. macOS, Ubuntu, Windows]
## 📋 Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published
## 🚀 Deployment Notes
Any special deployment considerations or notes.
## 📝 Additional Notes
Any additional information that reviewers should know.
---
**Note**: This repository is a component of the QQQ framework. For general QQQ changes, please use the [main QQQ repository](https://github.com/Kingsrook/qqq).
+56
View File
@@ -0,0 +1,56 @@
# Changelog
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]
### Added
- Comprehensive README with detailed usage examples
- CONTRIBUTING.md with development guidelines
- SECURITY.md with security policy and reporting procedures
- CHANGELOG.md for tracking changes
### Changed
- Updated README to follow QQQ framework standards
- Enhanced documentation structure and organization
## [2.1] - 2024-01-XX
### 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
### Changed
- Improved orb structure and organization
- Enhanced error handling and validation
- Updated dependencies and security patches
### Fixed
- Various bug fixes and stability improvements
## [2.0] - 2023-XX-XX
### Added
- Initial CircleCI orb implementation
- Basic Maven project support
- Core CI/CD workflows
### Changed
- Migrated from custom CI/CD to CircleCI orbs
## [1.x] - 2022-XX-XX
### Added
- Legacy CI/CD implementation
- Basic automation scripts
---
**Note**: For detailed release information and breaking changes, see the [QQQ Wiki](https://github.com/Kingsrook/qqq/wiki).
+4
View File
@@ -0,0 +1,4 @@
# Code of Conduct
See Project level [Code of Conduct](https://github.com/Kingsrook/qqq/blob/develop/CODE_OF_CONDUCT.md)
+3
View File
@@ -0,0 +1,3 @@
# Code Style Guide
* See Project [Code Style Guide](https://github.com/Kingsrook/qqq/blob/develop/CODE_STYLE.md)
+4
View File
@@ -0,0 +1,4 @@
# Contributing to QBit User Role Permissions
* See Project [Contributing](https://github.com/Kingsrook/qqq/blob/develop/CONTRIBUTING.md)
+1 -1
View File
@@ -1,6 +1,6 @@
MIT License
Copyright (c) 2023 <organization>
Copyright (c) 2021-2024 Kingsrook, LLC
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
+79 -27
View File
@@ -1,23 +1,24 @@
# QQQ Orb Development Makefile
# Provides convenient commands for orb development, validation, and publishing
.PHONY: help pack validate clean test publish dev
.PHONY: help pack validate clean test publish-snapshot publish-release dev check-clean check-branch
# Default target
help:
@echo "QQQ Orb Development Commands:"
@echo ""
@echo " make pack - Pack the orb using 'orb pack' (recommended for orb development)"
@echo " make validate - Validate the packed orb"
@echo " make test - Pack and validate the orb"
@echo " make clean - Remove packed orb files"
@echo " make dev - Development workflow: pack, validate, and show status"
@echo " make lint - Run all CircleCI-style linting checks"
@echo " make publish - Show publishing instructions (requires manual steps)"
@echo " make pack - Pack the orb using 'orb pack' (recommended for orb development)"
@echo " make validate - Validate the packed orb"
@echo " make test - Pack and validate the orb"
@echo " make clean - Remove packed orb files"
@echo " make dev - Development workflow: pack, validate, and show status"
@echo " make lint - Run all CircleCI-style linting checks"
@echo " make publish-snapshot - Interactive snapshot release (dev:snapshot)"
@echo " make publish-release - Interactive production release (tagged version)"
@echo ""
@echo "Key Files:"
@echo " src/@orb.yml - Main orb definition"
@echo " target/qqq-orb-packed.yml - Packed orb (generated)"
@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
pack:
@@ -80,25 +81,76 @@ dev: validate
@echo "Next steps:"
@echo " 1. Review the packed orb: cat target/qqq-orb-packed.yml"
@echo " 2. Test with a project configuration"
@echo " 3. Publish when ready: make publish"
@echo " 3. Publish when ready:"
@echo " - make publish-snapshot (for dev testing)"
@echo " - make publish-release (for production)"
# Show publishing instructions
publish:
@echo "🚀 Orb Publishing Instructions:"
# Check if working directory is clean
check-clean:
@if [ -n "$$(git status --porcelain)" ]; then \
echo "❌ Working directory is not clean. Commit changes first."; \
exit 1; \
fi
# Check if we're on the right branch for releases
check-branch:
@current=$$(git branch --show-current); \
if [ "$$current" != "main" ] && [ "$$current" != "master" ]; then \
echo "⚠️ Warning: You're on branch '$$current', not main/master"; \
echo " This is recommended for production releases."; \
read -p "Continue anyway? [y/N]: " confirm; \
if [ "$$confirm" != "y" ] && [ "$$confirm" != "Y" ]; then \
exit 1; \
fi; \
fi
# Interactive snapshot release (dev:snapshot)
publish-snapshot: check-clean lint validate
@echo "🚀 Publishing Snapshot Release"
@echo ""
@echo "1. Ensure you're logged in to CircleCI CLI:"
@echo " circleci auth login"
@echo "This will publish to: kingsrook/qqq-orb@dev:snapshot"
@echo ""
@echo "2. Build the orb first (if not already done):"
@echo " make dev"
@read -p "Continue with snapshot release? [y/N]: " confirm; \
if [ "$$confirm" != "y" ] && [ "$$confirm" != "Y" ]; then \
echo "❌ Release cancelled"; \
exit 1; \
fi; \
echo ""; \
echo "📦 Publishing snapshot..."; \
circleci orb publish target/qqq-orb-packed.yml kingsrook/qqq-orb@dev:snapshot; \
echo "✅ Snapshot published successfully!"
# Interactive production release (tagged version)
publish-release: check-clean check-branch lint validate
@echo "🚀 Publishing Production Release"
@echo ""
@echo "3. Publish the orb:"
@echo " circleci orb publish target/qqq-orb-packed.yml kingsrook/qqq-orb@dev:alpha"
@echo "This will create a git tag and publish a production version."
@echo ""
@echo "4. For production release:"
@echo " circleci orb publish target/qqq-orb-packed.yml kingsrook/qqq-orb@2.1.0"
@echo ""
@echo "5. Promote dev version to production:"
@echo " circleci orb publish promote kingsrook/qqq-orb@dev:alpha patch"
@echo ""
@echo "📚 More info: https://circleci.com/docs/orb-author/#publishing-an-orb"
@latest=$$(git tag -l 'v*' | sort -V | tail -1); \
if [ -n "$$latest" ]; then \
echo "Latest version: $$latest"; \
next=$$(echo "$$latest" | sed 's/^v//' | awk -F. '{$$NF++; print $$1"."$$2"."$$NF}'); \
echo "Suggested next version: v$$next"; \
else \
echo "No previous versions found. Starting with v0.1.0"; \
next="0.1.0"; \
fi; \
echo ""; \
read -p "Enter version [v$$next]: " version; \
version=$${version:-v$$next}; \
if [ "$$version" != "v$$(echo $$version | sed 's/^v//')" ]; then \
echo "❌ Version must start with 'v' (e.g., v1.0.0)"; \
exit 1; \
fi; \
if git tag -l | grep -q "^$$version$$"; then \
echo "❌ Tag $$version already exists"; \
exit 1; \
fi; \
echo ""; \
echo "Creating tag $$version..."; \
git tag -a "$$version" -m "Release $$version"; \
echo "Publishing kingsrook/qqq-orb@$$(echo $$version | sed 's/^v//')..."; \
circleci orb publish target/qqq-orb-packed.yml kingsrook/qqq-orb@$$(echo $$version | sed 's/^v//'); \
echo "Pushing tag to remote..."; \
git push origin "$$version"; \
echo "✅ Production release $$version published successfully!"
+249 -66
View File
@@ -1,8 +1,51 @@
# QQQ Orb
CircleCI orb for Maven projects using GitFlow. Provides automated building, testing, version management, and Maven Central publishing.
[![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)
## Quick Start
> **CircleCI Orb for QQQ Framework Projects**
CircleCI orb for Maven and Node.js projects using GitFlow. Provides automated building, testing, version management, and publishing to Maven Central and npm registries.
## 🚀 Overview
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.
### What This Repository Contains
- **CircleCI Orb**: Reusable CI/CD workflows and commands
- **GitFlow Integration**: Automated branching and version management
- **Multi-Platform Support**: Maven (Java) and npm (Node.js) project support
- **Publishing Automation**: Automated publishing to Maven Central and npm
- **Testing Framework**: Comprehensive testing with coverage reporting
### What This Repository Does NOT Contain
- **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
- **YAML**: Configuration and workflow definitions
### Core Capabilities
- **Automated Building**: Maven and npm project compilation
- **Testing**: Unit tests, integration tests, and coverage reporting
- **Version Management**: Automated semantic versioning based on GitFlow
- **Publishing**: Maven Central and npm registry publishing
- **Documentation**: Automated documentation generation and publishing
## 🚀 Quick Start
### Using the Orb
@@ -54,60 +97,59 @@ workflows:
### Required Context
Set up `qqq-maven-registry-credentials` context in CircleCI:
- `MAVEN_USERNAME`, `MAVEN_PASSWORD`: Sonatype credentials
- `GPG_PRIVATE_KEY_B64`, `GPG_KEYNAME`, `GPG_PASSPHRASE`: GPG signing
- `GITHUB_TOKEN`: GitHub releases
- `RDBMS_PASSWORD`: Database testing
| 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 |
### Project Requirements
- `pom.xml` with `<revision>` property
- `/tmp/circleci/mvn-settings.xml` (auto-generated if missing)
- `docs/index.adoc` (optional, for documentation)
- **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)
## Development
## 📁 Repository Structure
### Prerequisites
```bash
# Install CircleCI CLI
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | sudo bash
# Install linting tools
brew install shellcheck yamllint # macOS
```
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 # 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
```
### Commands
```bash
make pack # Pack orb (resolves <<include()>>)
make validate # Validate packed orb
make lint # Run all linting checks
make dev # Pack + validate
make clean # Clean build artifacts
```
## 🎯 Available Jobs
### Publishing
```bash
make publish-dev # Publish as kingsrook/qqq-orb@dev:alpha
make publish # Publish as kingsrook/qqq-orb@X.Y.Z
```
## Version Management
Automated version calculation based on branch:
- `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)
**Main branch requires release tags**: `git tag -a v1.5.0 -m "Release 1.5.0" && git push origin v1.5.0`
## Available Jobs
| Job | Branch | Output |
|-----|--------|--------|
| `build` | Any | Compiled artifacts |
| `test` | Any | Test results + JaCoCo |
| `publish` | Any | Unified publishing based on branch_type parameter |
| 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 |
### Publish Job Parameters
@@ -115,27 +157,82 @@ Automated version calculation based on branch:
|-----------|------|---------|-------------|
| `branch_type` | string | "snapshot" | Branch type: snapshot, release_candidate, release, hotfix |
## Repository Structure
## 🔧 Development
```
src/
├── @orb.yml # Orb definition
├── commands/ # Reusable commands
├── jobs/ # Complete workflow jobs
├── scripts/ # Shell scripts (<<include()>>)
└── examples/ # Usage examples
### Prerequisites
```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
```
## Project Links
### Development Commands
- **Main Project**: [QQQ Framework](https://github.com/Kingsrook/qqq)
- **Issues & Planning**: [QQQ Issues](https://github.com/Kingsrook/qqq/issues)
- **Documentation**: [QQQ Docs](https://github.com/Kingsrook/qqq/tree/main/docs)
- **CircleCI Registry**: [kingsrook/qqq-orb](https://circleci.com/developer/orbs/orb/kingsrook/qqq-orb)
```bash
make pack # Pack orb (resolves <<include()>>)
make validate # Validate packed orb
make lint # Run all linting checks
make dev # Pack + validate
make clean # Clean build artifacts
```
## Usage Examples
### Publishing Commands
```bash
make publish-snapshot # Publish as kingsrook/qqq-orb@dev:snapshot
make publish-release # Publish as kingsrook/qqq-orb@X.Y.Z
```
## 📋 Version Management
Automated version calculation based on GitFlow branches:
| 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` |
**Main branch requires release tags**:
```bash
git tag -a v1.5.0 -m "Release 1.5.0"
git push origin v1.5.0
```
## 🧪 Testing
### Running Tests
```bash
# Run all tests
make test
# Run linting checks
make lint
# Validate orb configuration
make validate
```
### Test Coverage
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
- **Integration Testing**: End-to-end workflow testing
## 📦 Usage Examples
### Maven Project (Backend Only)
**Backend only (default)**:
```yaml
jobs:
- qqq-orb/publish:
@@ -143,7 +240,8 @@ jobs:
branch_type: snapshot
```
**Release with GitHub release**:
### Node.js Project (Frontend Only)
```yaml
jobs:
- qqq-orb/publish:
@@ -151,6 +249,91 @@ jobs:
branch_type: release
```
## License
### Hybrid Project (Maven + Node.js)
MIT License - see [LICENSE](LICENSE)
```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`
5. **Commit your changes**: `git commit -m 'Add amazing feature'`
6. **Push to the branch**: `git push origin feature/amazing-feature`
7. **Open a Pull Request** to the main QQQ repository
### Code Standards
- **YAML**: Follow CircleCI orb best practices
- **Shell Scripts**: Use ShellCheck for validation
- **Documentation**: Update README and inline documentation
- **Testing**: Comprehensive test coverage
## 📄 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**
+3
View File
@@ -0,0 +1,3 @@
# Security Policy
* See Project [Security Policy](https://github.com/Kingsrook/qqq/blob/develop/SECURITY.md)
+1
View File
@@ -14,3 +14,4 @@ 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
File renamed without changes.
+17
View File
@@ -0,0 +1,17 @@
description: >
Builds the package
- Cleans and builds the package
- Persists build artifacts to workspace for use in publishing jobs
steps:
- run:
name: "Clean and build"
command: npm run clean-and-install
# Persist build artifacts to workspace for use in publishing jobs
- persist_to_workspace:
root: .
paths:
- lib/ # Compiled TypeScript output
- package.json # Updated package manifest
- README.md # Documentation
- LICENSE # License file
+14
View File
@@ -0,0 +1,14 @@
description: >
Installs Node.js dependencies
- Installs Node.js dependencies using NPM
- Builds the TypeScript project
steps:
# Install packages with NPM, using CircleCI's optimized caching
- node/install-packages:
pkg-manager: npm
cache-path: node_modules
# Build TypeScript project after dependencies are installed
- run:
name: "Build TypeScript project"
command: npm run prepublishOnly
+18
View File
@@ -0,0 +1,18 @@
description: >
Manages the version of the project
- Adds SSH keys for Git operations
- Sets up Git identity for version commits
- Synchronizes NPM version
- Commits version changes if modified
steps:
- add_ssh_keys # injects the CircleCI User Key (write-capable)
- run:
name: Set up Git identity for version commits
command: <<include(scripts/node_git_config.sh)>>
- run:
name: "Synchronize NPM version"
command: <<include(scripts/sync-npm-version.sh)>>
- run:
name: Commit version changes if modified
command: <<include(scripts/node_version_commit.sh)>>
+12
View File
@@ -0,0 +1,12 @@
description: >
Publishes the package to NPM
- Sets up NPM authentication
- Publishes the package to NPM
steps:
- run:
name: "Setup NPM authentication"
command: <<include(scripts/node_npm_auth.sh)>>
- run:
name: "Publish to NPM"
command: npm publish --access public
+12
View File
@@ -0,0 +1,12 @@
description: >
Runs the tests and linting
- Runs the tests
- Runs the linting
steps:
- run:
name: "Run tests"
command: npm test
- run:
name: "Run linting"
command: npm run lint
+1 -1
View File
@@ -5,7 +5,7 @@ description: >
usage:
version: 2.1
orbs:
qqq-orb: kingsrook/qqq-orb@2.1
qqq-orb: kingsrook/qqq-orb@0.3.1
workflows:
# Test workflow for feature branches
+2 -8
View File
@@ -13,15 +13,9 @@ parameters:
steps:
- checkout
- manage_version
- mvn_manage_version
- frontend_build
- frontend_test
- frontend_package
- mvn_jar_deploy
- when:
condition:
or:
- equal: ["snapshot", << parameters.branch_type >>]
- equal: ["release_candidate", << parameters.branch_type >>]
steps:
- git_operations
- git_operations
+17 -9
View File
@@ -10,21 +10,29 @@ parameters:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
check_middleware_api_versions:
type: boolean
default: false
description: "Whether to run middleware API version checks"
publish_asciidoc:
type: boolean
default: false
description: "Whether to publish AsciiDoc documentation"
steps:
- checkout
- mvn_build
- manage_version
- mvn_manage_version
- attach_workspace:
at: .
- mvn_verify
- check_middleware_api_versions
- mvn_jar_deploy
- when:
condition:
or:
- equal: ["snapshot", << parameters.branch_type >>]
- equal: ["release_candidate", << parameters.branch_type >>]
condition: << parameters.check_middleware_api_versions >>
steps:
- git_operations
- publish_asciidoc
- check_middleware_api_versions
- mvn_jar_deploy
- git_operations
- when:
condition: << parameters.publish_asciidoc >>
steps:
- publish_asciidoc
+10 -1
View File
@@ -6,8 +6,17 @@ description: >
executor: localstack/default
parameters:
check_middleware_api_versions:
type: boolean
default: false
description: "Whether to run middleware API version checks"
steps:
- checkout
- mvn_build
- mvn_verify
- check_middleware_api_versions
- when:
condition: << parameters.check_middleware_api_versions >>
steps:
- check_middleware_api_versions
+22
View File
@@ -0,0 +1,22 @@
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
executor: localstack/default
parameters:
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
steps:
- checkout
- node_install_dependencies
- node_run_tests
- node_manage_version
- attach_workspace:
at: .
- node_build_package
- node_publish
+17
View File
@@ -0,0 +1,17 @@
description: >
Unified test-only job for all branch types
Handles testing based on branch type
Supports: snapshot, release_candidate, release, and hotfix workflows
executor: localstack/default
parameters:
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
steps:
- checkout
- node_install_dependencies
- node_run_tests
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
Regular → Executable
View File
File mode changed.
+8 -1
View File
@@ -27,7 +27,14 @@ if [[ -n "$(git status --porcelain pom.xml)" ]]; then
NEW_VERSION=$(grep '<revision>' pom.xml | sed 's/.*<revision>//;s/<.*//')
git add pom.xml
git commit -m "Bump version to $NEW_VERSION [skip ci]"
git push origin "HEAD:${CIRCLE_BRANCH}"
if [ -n "$CIRCLE_BRANCH" ]; then
git push origin "HEAD:${CIRCLE_BRANCH}"
else
# Tag build: push to main (or your default branch)
git push origin HEAD:main
fi
echo "Version updated to: $NEW_VERSION and pushed"
else
echo "No version change needed"
+18
View File
@@ -0,0 +1,18 @@
#!/bin/bash
############################################################################
## node_git_config.sh
## Git Configuration Setup for Node.js Projects
##
## This script sets up Git identity for version commits in Node.js projects.
## It configures the Git user email and name for CircleCI operations.
##
## Usage: Called by node_manage_version command
## Output: Configures Git identity for CI operations
############################################################################
set -e
echo "Setting up Git identity for version commits"
git config user.email "ci@kingsrook.com"
git config user.name "CircleCI"
+24
View File
@@ -0,0 +1,24 @@
#!/bin/bash
############################################################################
## node_npm_auth.sh
## NPM Authentication Setup Script
##
## This script configures NPM authentication for publishing to the public registry.
## It sets up the authentication token and verifies the authentication.
##
## Process:
## 1. Configures NPM authentication for public registry
## 2. Verifies authentication by checking current user
##
## Usage: Called by node_publish command
## Output: Sets up NPM authentication and verifies it
############################################################################
set -e
echo "Configuring NPM authentication for public registry"
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
echo "Verifying authentication by checking current user"
npm whoami
+32
View File
@@ -0,0 +1,32 @@
#!/bin/bash
############################################################################
## node_version_commit.sh
## Node.js Version Commit Management Script
##
## This script handles committing version changes to Git for Node.js projects.
## It checks if the package.json file has been modified and commits the changes if needed.
## It also pushes the changes back to the current branch.
##
## Process:
## 1. Checks if package.json has been modified
## 2. Extracts the new version from package.json
## 3. Commits the changes with skip ci flag
## 4. Pushes changes to the current branch
##
## Usage: Called by node_manage_version command
## Output: Commits and pushes version changes if package.json was modified
############################################################################
set -e
echo "Checking for package.json version changes"
if [[ -n "$(git status --porcelain package.json)" ]]; then
NEW_VERSION=$(grep '"version"' package.json | sed 's/.*"version": "//;s/".*//')
git add package.json
git commit -m "Bump version to $NEW_VERSION [skip ci]"
git push origin "HEAD:${CIRCLE_BRANCH}"
echo "Version updated to: $NEW_VERSION and pushed"
else
echo "No version change needed"
fi
+105
View File
@@ -0,0 +1,105 @@
#!/bin/bash
set -e
# NPM Version Synchronization Script for qqq-frontend-core
# This script updates package.json version based on the current GitFlow branch and versioning policy
PACKAGE_JSON="package.json"
DRY_RUN=false
if [[ "$1" == "--dry-run" ]]; then
DRY_RUN=true
echo "DRY RUN MODE - No changes will be made"
fi
# Get current branch
CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"
# Get current NPM version
NPM_VERSION=$(grep '"version"' $PACKAGE_JSON | sed 's/.*"version": "//;s/".*//')
echo "Current NPM version: $NPM_VERSION"
# Determine target version based on GitFlow branch
if [[ "$CURRENT_BRANCH" == "main" ]]; then
# Main branch - should be a release version (e.g., 1.0.0)
# Extract major.minor from current version
MAJOR_MINOR="${NPM_VERSION%.*}"
TARGET_VERSION="$MAJOR_MINOR.0"
echo "Main branch detected - targeting release version: $TARGET_VERSION"
elif [[ "$CURRENT_BRANCH" == "develop" ]]; then
# Develop branch - should be a snapshot version (e.g., 1.0.127-SNAPSHOT)
# Increment patch version for develop
MAJOR_MINOR_PATCH="${NPM_VERSION%-*}"
MAJOR_MINOR="${MAJOR_MINOR_PATCH%.*}"
PATCH="${MAJOR_MINOR_PATCH##*.}"
NEW_PATCH=$((PATCH + 1))
TARGET_VERSION="$MAJOR_MINOR.$NEW_PATCH-SNAPSHOT"
echo "Develop branch detected - targeting snapshot version: $TARGET_VERSION"
elif [[ "$CURRENT_BRANCH" == release/* ]]; then
# Release branch - should be a release candidate (e.g., 1.0.0-RC.1, 1.0.0-RC.2, etc.)
RELEASE_VERSION=$(echo "$CURRENT_BRANCH" | sed 's/release\///')
# Check if current version is already an RC for this release
if [[ "$NPM_VERSION" =~ ^$RELEASE_VERSION-RC\.([0-9]+)$ ]]; then
# Increment existing RC number
CURRENT_RC=${BASH_REMATCH[1]}
NEW_RC=$((CURRENT_RC + 1))
TARGET_VERSION="$RELEASE_VERSION-RC.$NEW_RC"
echo "Release branch detected - incrementing RC from $NPM_VERSION to $TARGET_VERSION"
else
# First RC for this release
TARGET_VERSION="$RELEASE_VERSION-RC.1"
echo "Release branch detected - creating first RC: $TARGET_VERSION"
fi
elif [[ "$CURRENT_BRANCH" == hotfix/* ]]; then
# Hotfix branch - should be a patch version (e.g., 1.0.1)
HOTFIX_VERSION=$(echo "$CURRENT_BRANCH" | sed 's/hotfix\///')
TARGET_VERSION="$HOTFIX_VERSION"
echo "Hotfix branch detected - targeting patch version: $TARGET_VERSION"
else
# Feature branch - should be a snapshot version
MAJOR_MINOR_PATCH="${NPM_VERSION%-*}"
MAJOR_MINOR="${MAJOR_MINOR_PATCH%.*}"
PATCH="${MAJOR_MINOR_PATCH##*.}"
NEW_PATCH=$((PATCH + 1))
TARGET_VERSION="$MAJOR_MINOR.$NEW_PATCH-SNAPSHOT"
echo "Feature branch detected - targeting snapshot version: $TARGET_VERSION"
fi
echo "Target version: $TARGET_VERSION"
if [[ "$NPM_VERSION" == "$TARGET_VERSION" ]]; then
echo "✅ Versions are already synchronized"
exit 0
fi
if [[ "$DRY_RUN" == "true" ]]; then
echo "DRY RUN: Would update package.json version from '$NPM_VERSION' to '$TARGET_VERSION'"
echo "Command: sed -i 's/\"version\": \"$NPM_VERSION\"/\"version\": \"$TARGET_VERSION\"/' $PACKAGE_JSON"
exit 0
fi
echo "Updating package.json version from '$NPM_VERSION' to '$TARGET_VERSION'"
# Update version in package.json (macOS compatible)
if [[ "$OSTYPE" == "darwin"* ]]; then
sed -i '' "s/\"version\": \"$NPM_VERSION\"/\"version\": \"$TARGET_VERSION\"/" $PACKAGE_JSON
else
sed -i "s/\"version\": \"$NPM_VERSION\"/\"version\": \"$TARGET_VERSION\"/" $PACKAGE_JSON
fi
# Verify the update
ACTUAL_NPM_VERSION=$(grep '"version"' $PACKAGE_JSON | sed 's/.*"version": "//;s/".*//')
if [[ "$ACTUAL_NPM_VERSION" == "$TARGET_VERSION" ]]; then
echo "✅ NPM version successfully updated to: $ACTUAL_NPM_VERSION"
else
echo "❌ NPM version update failed. Expected: $TARGET_VERSION, Got: $ACTUAL_NPM_VERSION"
exit 1
fi
echo ""
echo "=== NPM version synchronization complete ==="
echo "Previous: $NPM_VERSION"
echo "Current: $ACTUAL_NPM_VERSION"
echo "Branch: $CURRENT_BRANCH"