Compare commits

...
6 Commits
15 changed files with 538 additions and 84 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
+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 -7
View File
@@ -18,10 +18,4 @@ steps:
- 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
+16 -8
View File
@@ -10,6 +10,14 @@ 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
@@ -18,13 +26,13 @@ steps:
- 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
+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"