Initial commit: dram with native pgo (pre-kura)

Author: kivraDawi

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,56 @@
+## Description
+
+<!-- Describe your changes in detail -->
+
+## Type of Change
+
+<!-- Mark the relevant option with an 'x' -->
+
+- [ ] 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
+- [ ] Performance improvement
+- [ ] Code refactoring
+- [ ] Test updates
+
+## Changes Made
+
+<!-- List the specific changes you made -->
+
+-
+-
+-
+
+## Testing
+
+<!-- Describe the tests you ran to verify your changes -->
+
+- [ ] All existing tests pass (`make test`)
+- [ ] Added new tests for new functionality
+- [ ] Tested manually (describe what you tested)
+
+## Checklist
+
+- [ ] My code follows the project's coding style
+- [ ] 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 updated the version in `src/dram.app.src` if this is a release
+
+## Release Notes
+
+<!-- If this PR should trigger a release, describe what users need to know -->
+
+<!-- Example:
+### Added
+- New unique jobs feature to prevent duplicate job insertion
+- LISTEN/NOTIFY optimization for instant job execution
+
+### Changed
+- Improved stager performance by reducing polling interval
+
+### Fixed
+- Fixed pattern matching bug in unique job checking
+-->

.github/workflows/README.md

@@ -0,0 +1,284 @@
+# GitHub Workflows
+
+This directory contains GitHub Actions workflows for CI/CD automation.
+
+## Workflows
+
+### CI (`ci.yml`)
+
+Runs on every pull request to `main` and on pushes to `main`.
+
+**What it does:**
+- Runs multiple quality checks in parallel for speed
+- Compiles the project once and shares build artifacts
+- Checks code formatting with `erlfmt`
+- Runs `xref` (cross-reference analysis)
+- Runs `dialyzer` (type checking)
+- Runs all `eunit` tests
+- Uses PostgreSQL 16 service container for testing
+- Caches dependencies and PLT for faster builds
+- Uploads test results as artifacts
+
+**Test Environment:**
+- Erlang/OTP: 28.3.1
+- rebar3: 3.26.0
+- PostgreSQL: 16
+
+**Job Execution Flow:**
+```
+┌─────────────┐
+│   Format    │ (runs independently)
+└─────────────┘
+
+┌─────────────┐
+│   Compile   │ (compiles and uploads artifacts)
+└─────────────┘
+       │
+       ├──────────────┬──────────────┬──────────────┐
+       ▼              ▼              ▼              ▼
+┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+│   Xref   │   │ Dialyzer │   │  Tests   │   (parallel)
+└──────────┘   └──────────┘   └──────────┘
+```
+
+**Quality Checks (run in parallel after compile):**
+1. **Code Formatting** - Runs independently (fastest)
+2. **Compile** - Builds project once, shares with other jobs
+3. **Xref** - Cross-reference analysis (parallel)
+4. **Dialyzer** - Type checking (parallel, uses PLT cache)
+5. **Tests** - Full test suite with PostgreSQL (parallel)
+
+### Release (`release.yml`)
+
+**Automatically creates releases** when code is merged to `main` (excluding documentation-only changes).
+
+**What it does:**
+1. Gets the latest git tag (or `v0.0.0` if none exists)
+2. Determines version bump type based on commit messages:
+   - **Major bump** (1.0.0 → 2.0.0): Breaking changes
+   - **Minor bump** (1.0.0 → 1.1.0): New features
+   - **Patch bump** (1.0.0 → 1.0.1): Bug fixes and other changes
+3. Calculates new version number
+4. Updates `src/dram.app.src` with new version
+5. Generates categorized release notes from commits
+6. Creates git tag and GitHub release
+7. Commits version bump back to main
+
+**Version Bump Logic:**
+- `feat!:` or `BREAKING CHANGE:` → **Major** bump
+- `feat:` or `feature:` → **Minor** bump
+- `fix:`, `bugfix:`, or any other commit → **Patch** bump
+
+**Automatic Release Notes:**
+- Categorizes commits: Breaking Changes, Features, Bug Fixes, Other Changes
+- Includes installation instructions
+- Adds link to full changelog
+
+## Creating a Release
+
+### Simple Workflow (Recommended)
+
+Just merge your PR to `main` - releases happen automatically!
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/my-awesome-feature
+   ```
+
+2. **Make your changes and commit using conventional commits:**
+   ```bash
+   # For a new feature (minor version bump)
+   git commit -m "feat: add unique jobs support"
+
+   # For a bug fix (patch version bump)
+   git commit -m "fix: correct pattern matching in job claiming"
+
+   # For a breaking change (major version bump)
+   git commit -m "feat!: change job insertion API"
+   # or
+   git commit -m "feat: new API
+
+   BREAKING CHANGE: The insert function now requires an options map"
+   ```
+
+3. **Push and create PR:**
+   ```bash
+   git push origin feature/my-awesome-feature
+   ```
+
+4. **Merge the PR:**
+   - CI tests will run automatically
+   - Once merged, the release workflow automatically:
+     - Bumps version based on commits
+     - Creates tag `vX.Y.Z`
+     - Publishes GitHub release with notes
+     - Updates `src/dram.app.src`
+
+### Conventional Commit Format
+
+Use these prefixes to control version bumping:
+
+**Major version bump (breaking changes):**
+```bash
+feat!: change job insertion API
+fix!: remove deprecated cancel_all function
+```
+
+**Minor version bump (new features):**
+```bash
+feat: add unique jobs feature
+feature: implement job priorities
+```
+
+**Patch version bump (fixes and other):**
+```bash
+fix: correct timeout handling
+bugfix: resolve connection pool issue
+docs: update README
+chore: update dependencies
+refactor: simplify queue logic
+test: add more test cases
+```
+
+### Release Notes Example
+
+For commits:
+```
+feat: add unique jobs support
+fix: correct pattern matching bug
+chore: update dependencies
+```
+
+The workflow generates:
+```markdown
+# Dram 0.2.0
+
+## What's Changed
+
+### ✨ Features
+- feat: add unique jobs support (a1b2c3d)
+
+### 🐛 Bug Fixes
+- fix: correct pattern matching bug (d4e5f6g)
+
+### 📝 Other Changes
+- chore: update dependencies (h8i9j0k)
+
+## Installation
+...
+```
+
+## Manual Version Override (Advanced)
+
+If you need to set a specific version manually:
+
+1. **Update `src/dram.app.src`:**
+   ```erlang
+   {vsn, "2.0.0"}
+   ```
+
+2. **Commit with `[skip ci]` to prevent duplicate releases:**
+   ```bash
+   git commit -m "chore: bump version to 2.0.0 [skip ci]"
+   ```
+
+3. **Merge to main** - workflow will detect the existing version and create the release
+
+## Skipping Releases
+
+The release workflow automatically skips if:
+- Only documentation files changed (`.md`, `docs/`)
+- Changes only affect workflow files (`.github/`)
+- Commit message contains `[skip ci]` or `[skip release]`
+
+## Example Workflow
+
+```bash
+# 1. Create feature branch
+git checkout -b feat/add-scheduling
+
+# 2. Make changes and commit
+git add .
+git commit -m "feat: add job scheduling support"
+
+# 3. Push and create PR
+git push origin feat/add-scheduling
+
+# 4. CI runs tests automatically
+
+# 5. Merge PR to main
+# → Release workflow runs
+# → Version bumps from 0.1.0 to 0.2.0 (minor bump for "feat:")
+# → Tag v0.2.0 created
+# → GitHub release published
+# → src/dram.app.src updated automatically
+```
+
+## Running CI Checks Locally
+
+Before pushing your PR, run the same checks that CI runs:
+
+```bash
+# Run all quality checks
+make check
+
+# Or run individually
+make format     # Check code formatting
+make xref       # Cross-reference analysis
+make dialyzer   # Type checking
+make test       # Run tests
+```
+
+**Pre-commit checklist:**
+```bash
+# 1. Format your code
+rebar3 fmt
+
+# 2. Run all checks
+make check
+
+# 3. Run tests
+make test
+
+# 4. Commit and push
+git add .
+git commit -m "feat: my awesome feature"
+git push
+```
+
+## Requirements
+
+The workflows require:
+- **Repository permissions:** `contents: write` for creating releases
+- **No secrets needed:** Uses `GITHUB_TOKEN` (automatic)
+
+## Troubleshooting
+
+### Release not created after merge
+
+**Check:**
+1. Did you use conventional commit format? (`feat:`, `fix:`, etc.)
+2. Does your commit contain `[skip ci]`?
+3. Did you only change documentation?
+4. Check the Actions tab for workflow run details
+
+### Wrong version bump
+
+**Fix:**
+- Use correct commit prefix:
+  - `feat:` for features (minor bump)
+  - `fix:` for fixes (patch bump)
+  - `feat!:` for breaking changes (major bump)
+
+### Multiple commits in PR
+
+The workflow examines the **merge commit message**, so:
+- Squash commits before merging, OR
+- Use a descriptive merge commit message with proper prefix
+
+### Tests failing on PR
+
+**Check:**
+1. Do tests pass locally? (`make test`)
+2. Is PostgreSQL service starting correctly in CI?
+3. Check Actions tab for detailed error logs