Contributing to ThemisDB

Thank you for your interest in contributing to ThemisDB! This document provides guidelines and instructions for contributing.

🤝 Contributing to ThemisDB

Thank you for your interest in making ThemisDB better!

📋 Table of Contents

Section	Description
🤝 Code of Conduct	Community guidelines
🚀 Getting Started	Set up development environment
💻 Development Workflow	Branching and committing
✅ Code Quality Standards	Enforced quality checks
📋 License Compliance	License policy and compliance
🔄 Pull Request Process	Submitting changes
🏷️ Issue Labels	GitHub label system
🐛 Reporting Bugs	Bug report guidelines
💡 Feature Requests	Suggesting enhancements
📝 Documentation	Living documentation and continuous review process
📦 Package Maintenance	Platform packaging

🤝 Code of Conduct

Important

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to:

Be respectful and constructive in all interactions
Welcome newcomers and help them get started
Assume good intentions in discussions
Focus on what is best for the community and project

Please read the full Code of Conduct for details.

Getting Started

Prerequisites

Development Environment Setup

1. Clone the repository:

git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB

2. Install dependencies:

Linux/macOS:

./setup.sh

Windows:

.\setup.ps1

3. Build the project:

Linux/macOS:

./build.sh

Windows:

.\build.ps1

4. Run tests:

cd build
ctest --output-on-failure

5. Optional Features (v1.3.0+):

ThemisDB has optional features that require specific build flags:

# Build with LLM support (requires llama.cpp)
cmake -B build -DTHEMIS_ENABLE_LLM=ON
git clone https://github.com/ggerganov/llama.cpp.git

# Build with HTTP/2 support
cmake -B build -DTHEMIS_ENABLE_HTTP2=ON

# Build with WebSocket support
cmake -B build -DTHEMIS_ENABLE_WEBSOCKET=ON

# Build with MQTT support
cmake -B build -DTHEMIS_ENABLE_MQTT=ON

# Build with PostgreSQL Wire Protocol
cmake -B build -DTHEMIS_ENABLE_POSTGRES_WIRE=ON

# Build with MCP Server support
cmake -B build -DTHEMIS_ENABLE_MCP=ON

# Build with Image Analysis plugins
cmake -B build -DTHEMIS_ENABLE_IMAGE_ANALYSIS=ON

# Build with all optional features
cmake -B build -DTHEMIS_ENABLE_ALL_PROTOCOLS=ON

🚀 Getting Started

Prerequisites

Tool	Minimum Version	Purpose
C++ Compiler	GCC 10+ / Clang 12+ / MSVC 2019+	Core compilation
CMake	3.20+	Build system
vcpkg	Latest	Dependency management
Git	2.x	Version control

Development Environment Setup

1️⃣ Clone the Repository

git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB

2️⃣ Install Dependencies

Linux/macOS:

./setup.sh

Windows:

.\setup.ps1

[!TIP] The setup script automatically installs vcpkg and all required dependencies.

3️⃣ Build the Project

Linux/macOS:

./build.sh

Windows:

.\build.ps1

[!NOTE] First build may take 10-15 minutes as vcpkg compiles dependencies from source.

4️⃣ Run Tests

cd build
ctest --output-on-failure

Expected result: All tests should pass ✅

5️⃣ Optional Features (v1.3.0+)

ThemisDB supports optional protocol and AI integrations:

Feature	CMake Flag	Dependencies
🤖 LLM Support	`-DTHEMIS_ENABLE_LLM=ON`	llama.cpp
🌐 HTTP/2	`-DTHEMIS_ENABLE_HTTP2=ON`	nghttp2
📡 WebSocket	`-DTHEMIS_ENABLE_WEBSOCKET=ON`	uWebSockets
📬 MQTT	`-DTHEMIS_ENABLE_MQTT=ON`	mosquitto
🐘 PostgreSQL Wire	`-DTHEMIS_ENABLE_POSTGRES_WIRE=ON`	libpq
🔌 MCP Server	`-DTHEMIS_ENABLE_MCP=ON`	-
🖼️ Image Analysis	`-DTHEMIS_ENABLE_IMAGE_ANALYSIS=ON`	OpenCV

Build with LLM support:

cmake -B build -DTHEMIS_ENABLE_LLM=ON
git clone https://github.com/ggerganov/llama.cpp.git
cmake --build build

Build with all protocols:

cmake -B build -DTHEMIS_ENABLE_ALL_PROTOCOLS=ON
cmake --build build

See ATTRIBUTIONS.md for third-party dependency information.

Running tests under Windows / WSL (developer tips)

If you build under WSL the default build output used by repository helper scripts is build-wsl/ (e.g. build-wsl/themis_tests and build-wsl/themis_server). Helper scripts (such as .tools/vault_dev_run.ps1) rely on this layout.
To run the GoogleTest binary directly in WSL and export JUnit XML to the Windows host:

# from PowerShell (host):
wsl bash -lc "cd /mnt/c/VCC/themis; ./build-wsl/themis_tests --gtest_output=xml:/mnt/c/Temp/themis_tests.xml"

Vault integration tests expect a reachable Vault at VAULT_ADDR and a valid token in VAULT_TOKEN. The repository includes a small helper .tools/vault_dev_run.ps1 which:
- starts a local Vault dev container, enables KV v2 at mount themis/, writes a 32‑byte base64 key to themis/keys/test_key, and runs the Vault tests from WSL (writing XML output to C:\Temp).
- Preconditions: Docker available locally and a WSL installation with repo mounted under /mnt/c/VCC/themis.

Install Code Quality Tools

Linux (Ubuntu/Debian):

sudo apt-get install -y clang-tidy cppcheck lcov gcovr

# Install gitleaks
wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.4/gitleaks_8.18.4_linux_x64.tar.gz
tar -xzf gitleaks_8.18.4_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

macOS:

brew install llvm cppcheck lcov gitleaks

Windows:

choco install llvm cppcheck gitleaks

Development Workflow

Important

ThemisDB uses a Git Flow branching strategy:

main = Production-ready release branch (protected)
develop = Active development branch (integration)
All features branch from develop and merge back to develop
See BRANCHING_STRATEGY.md for complete details

1. Create a Feature Branch

# IMPORTANT: Always branch from develop (not main)
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# OR for bug fixes
git checkout -b bugfix/bug-description

Branch naming conventions:

2. Make Your Changes

3. Run Code Quality Checks

Before committing, run local quality checks:

# Linux/macOS
./scripts/check-quality.sh

# Windows
.\scripts\check-quality.ps1

Auto-fix issues where possible:

# Linux/macOS
./scripts/check-quality.sh --fix

# Windows
.\scripts\check-quality.ps1 -Fix

4. Commit Your Changes

Write clear, descriptive commit messages:

<type>(<scope>): <subject>

<body>

<footer>

Examples:

feat(storage): Add checkpoint-based incremental backups


Closes #123

fix(query): Correct off-by-one error in pagination

The cursor offset calculation was incorrect for empty result sets,
causing the next page to skip the first result.

Fixes #456

Commit types:

5. Push and Create Pull Request

git push origin feature/your-feature-name

Create Pull Request:

Base Branch: develop (not main!)
Compare Branch: feature/your-feature-name
Add clear description of changes
Link related issues

Note

Pull requests should target the develop branch unless you are working on a hotfix for production.

💻 Development Workflow

Important

ThemisDB uses a Git Flow branching strategy:

🎯 main = Production-ready release branch (protected)
🚧 develop = Active development branch (integration)
🌿 All features branch from develop and merge back to develop
📖 See BRANCHING_STRATEGY.md for complete details

1️⃣ Create a Feature Branch

# IMPORTANT: Always branch from develop (not main)
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# OR for bug fixes
git checkout -b bugfix/bug-description

Branch Naming Conventions:

Prefix	Purpose	Example
`feature/`	🎉 New features	`feature/vector-search-optimization`
`fix/`	🐛 Bug fixes	`fix/connection-leak-in-pool`
`docs/`	📖 Documentation	`docs/improve-api-examples`
`refactor/`	♻️ Code refactoring	`refactor/extract-storage-interface`
`test/`	🧪 Test improvements	`test/add-transaction-edge-cases`
`perf/`	⚡ Performance	`perf/optimize-index-lookup`

2️⃣ Make Your Changes

Important

Best Practices:

✅ Write clean, maintainable code following C++17 standards
✅ Add unit tests for new functionality
✅ Update documentation as needed
✅ Keep commits focused and atomic

3️⃣ Run Code Quality Checks

Before committing, run local quality checks:

Linux/macOS

# Run all checks
./scripts/check-quality.sh

# Auto-fix issues
./scripts/check-quality.sh --fix

Windows

# Run all checks
.\scripts\check-quality.ps1

# Auto-fix issues
.\scripts\check-quality.ps1 -Fix

Tip

Use --fix to automatically resolve formatting and minor issues.

4️⃣ Commit Your Changes

Commit Message Format:

<type>(<scope>): <subject>

<body>

<footer>

Example Commits:

Feature Commit

feat(storage): Add checkpoint-based incremental backups

- Implement RocksDB checkpoint API integration
- Add WAL archiving with retention policies
- Create cross-platform backup scripts (PowerShell + Bash)
- Add systemd and Kubernetes automation examples

Closes #123

Bug Fix Commit

fix(query): Correct off-by-one error in pagination

The cursor offset calculation was incorrect for empty result sets,
causing the next page to skip the first result.

Fixes #456

Commit Types:

Type	Emoji	Description
`feat`	✨	New feature
`fix`	🐛	Bug fix
`docs`	📝	Documentation changes
`style`	💄	Code style (no logic change)
`refactor`	♻️	Code refactoring
`perf`	⚡	Performance improvements
`test`	✅	Test additions/improvements
`chore`	🔧	Build/tooling changes

5️⃣ Push and Create Pull Request

git push origin feature/your-feature-name

Note

Target Branch: Pull requests should target the develop branch (not main!) unless you are working on a hotfix for production.

When creating your PR:

Set Base to develop
Set Compare to your feature branch
Add clear description of changes
Link related issues with Closes #123
Add appropriate labels

Code Quality Standards

ThemisDB enforces strict code quality standards through automated CI checks:

Static Analysis (clang-tidy)

Common issues to avoid:

Linting (cppcheck)

Code Coverage

Generate local coverage report:

# After running tests with coverage
mkdir -p coverage
lcov --capture --directory build --output-file coverage/coverage.info
lcov --remove coverage/coverage.info '/usr/*' '*/vcpkg_installed/*' '*/tests/*' \
  --output-file coverage/coverage-filtered.info
genhtml coverage/coverage-filtered.info --output-directory coverage/html

# Open report
xdg-open coverage/html/index.html  # Linux
open coverage/html/index.html      # macOS
start coverage/html/index.html     # Windows

Secret Scanning (Gitleaks)

Avoid committing:

Use instead:

Code Style

Naming conventions:

File structure:

Comments:

✅ Code Quality Standards

Important

ThemisDB enforces strict code quality standards through automated CI checks.
All PRs must pass these checks before merging.

🔍 Static Analysis (clang-tidy)

Configuration Details

Enabled Checks:

bugprone-* - Detect potential bugs
clang-analyzer-* - Deep code analysis
cppcoreguidelines-* - C++ Core Guidelines compliance
modernize-* - Modern C++ features
performance-* - Performance optimizations
readability-* - Code readability

Configuration File: .clang-tidy

Auto-fix:

./scripts/check-quality.sh --fix  # Linux/macOS
.\scripts\check-quality.ps1 -Fix  # Windows

Warning

Common Issues to Avoid:

❌ Magic numbers → Use named constants
❌ Unnecessary copies → Use const& or std::move
❌ Missing override keyword
❌ C-style casts → Use static_cast/dynamic_cast

🧪 Linting (cppcheck)

Enabled Checks: All (with suppressions for known false positives)
Configuration: .cppcheck-suppressions
Purpose: Catch memory leaks, null pointer dereferences, undefined behavior

📊 Code Coverage

Component	Target	Critical Path
Overall	80%+	-
Storage Engine	-	90%+
Transaction Manager	-	90%+
Query Engine	-	90%+

Generate Local Coverage Report

# After running tests with coverage
mkdir -p coverage
lcov --capture --directory build --output-file coverage/coverage.info
lcov --remove coverage/coverage.info '/usr/*' '*/vcpkg_installed/*' '*/tests/*' \
   --output-file coverage/coverage-filtered.info
genhtml coverage/coverage-filtered.info --output-directory coverage/html

# Open report
xdg-open coverage/html/index.html  # Linux
open coverage/html/index.html      # macOS
start coverage/html/index.html     # Windows

🔐 Secret Scanning (Gitleaks)

Caution

CI fails immediately if secrets are detected!

Tool: Gitleaks
Configuration: .gitleaks.toml

❌ Never Commit:

API keys
Passwords
Private keys
Database credentials

✅ Use Instead:

Environment variables
.env.example templates (never .env)
Configuration placeholders (YOUR_API_KEY_HERE)

📋 License Compliance

Important

All dependencies must comply with ThemisDB's license policy!
The automated license compliance workflow blocks PRs with incompatible licenses.

License Policy:

Allowed: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Unlicense, CC0-1.0, MPL-2.0
Warning (Weak Copyleft): LGPL-2.1, LGPL-3.0, EPL-1.0, EPL-2.0 (acceptable with dynamic linking)
Blocked (Strong Copyleft): GPL-2.0, GPL-3.0, AGPL-3.0
Blocked: Proprietary, Commercial, UNLICENSED

Before adding dependencies:

Check the license - Verify it's in the allowed list
Review .license-policy.json - Consult the policy file
Document in PR - Mention the license in your pull request

If your PR is blocked:

Option A: Replace the dependency with a compatible alternative (preferred)
Option B: Request an exception by creating an issue with label license-exception

Automated Checks:

✅ Runs on every PR that changes dependencies
📊 Monthly audit on the first of each month
🔍 Scans vcpkg.json, package.json, and other dependency files
💬 Posts results as PR comment with detailed violations

Documentation:

Full License Compliance Process (German)
License Compliance Process (English)
License Policy File

🎨 Code Style

Naming Conventions

Element	Convention	Example
Namespaces	`lower_case`	`vccdb`, `themis`
Classes/Structs	`CamelCase`	`StorageEngine`, `HttpServer`
Functions	`camelCase`	`getValue`, `processQuery`
Variables	`lower_case`	`table_name`, `max_size`
Private Members	`lower_case_`	`db_path_`, `cache_size_`
Constants	`UPPER_CASE`	`MAX_CONNECTIONS`, `DEFAULT_PORT`

File Structure

include/<module>/<name>.h     # Header files
src/<module>/<name>.cpp       # Implementation files
tests/test_<module>_<feature>.cpp  # Test files

Comment Guidelines

Use // for single-line comments
Use /** ... */ for documentation (Doxygen style)
Explain why, not what (code should be self-documenting)

Example:

// Good: Explains WHY
// Use exponential backoff to prevent thundering herd
std::this_thread::sleep_for(std::chrono::milliseconds(delay));

// Bad: Explains WHAT (obvious from code)
// Sleep for delay milliseconds
std::this_thread::sleep_for(std::chrono::milliseconds(delay));

Pull Request Process

Before Submitting

Run all checks locally:
```
./scripts/check-quality.sh
```
Ensure all tests pass:
```
cd build
ctest --output-on-failure
```
Update documentation:
- Add/update relevant .md files in docs/
- Update README.md if needed
- Add docstrings for new public APIs
Add tests:
- Unit tests for new functions/classes
- Integration tests for new features
- Update existing tests if behavior changes

PR Description Template

## Description
Brief description of changes

## Type of Change
---

## 🔄 Pull Request Process

### Before Submitting

> [!IMPORTANT]
> **Pre-submission Checklist:**
> - ✅ All quality checks pass locally
> - ✅ All tests pass
> - ✅ Documentation updated
> - ✅ Tests added for new functionality

<details open>
<summary><b>1️⃣ Run All Checks Locally</b></summary>

```bash
./scripts/check-quality.sh  # Linux/macOS
.\scripts\check-quality.ps1  # Windows

This runs:

clang-tidy (static analysis)
cppcheck (linting)
Gitleaks (secret scanning)

2️⃣ Ensure All Tests Pass

cd build
ctest --output-on-failure

Expected: All tests should pass ✅

3️⃣ Update Documentation

📝 Add/update relevant .md files in docs/
📖 Update README.md if needed
💬 Add docstrings for new public APIs (Doxygen format)

4️⃣ Add Tests

Test Type	Purpose	Example
Unit Tests	Test individual functions/classes	`test_vector_search.cpp`
Integration Tests	Test feature workflows	`test_backup_restore.cpp`
Regression Tests	Ensure bugs stay fixed	`test_issue_456_pagination.cpp`

PR Description Template

## 📋 Description
Brief description of changes

## 🔖 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

## How Has This Been Tested?
Describe the tests you ran to verify your changes.

## Checklist
- [ ] My code follows the code style of this project
- [ ] 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
- [ ] I have run `./scripts/check-quality.sh` and fixed all issues

Review Process

Automated checks run on all PRs:
- Build (Linux + Windows)
- Tests
- Clang-tidy static analysis
- Cppcheck linting
- Code coverage
- Gitleaks secret scanning
Maintainer review:
- Code quality and style
- Test coverage
- Documentation
- Architecture fit
Address feedback:
- Make requested changes
- Push updates to the same branch
- Request re-review
Merge:
- Once approved and all checks pass
- Maintainer will squash and merge (preferred for feature/bugfix PRs to keep history clean)
- Merge commits are only used for release and hotfix branches

Merge Strategy Guidelines

Important

ThemisDB uses different merge strategies depending on the branch type:

Branch Type	Merge Method	Reason
feature/ → develop	Squash and merge ✅	Keeps develop history clean, one commit per feature
bugfix/ → develop	Squash and merge ✅	Keeps develop history clean, one commit per fix
release/ → main	Merge commit	Preserves full release history and commit metadata
hotfix/ → main	Merge commit	Preserves full hotfix history for audit purposes

Why squash merge for features/bugfixes?

✅ Cleaner, more readable git history
✅ One logical commit per feature/fix
✅ Easier to revert if needed
✅ Better changelog generation
❌ Development commits (WIP, fix typo, etc.) stay in feature branch

Configuring GitHub Repository Settings:

Maintainers should configure the repository settings on GitHub to enforce this:

Go to Settings → General → Pull Requests
Enable "Allow squash merging" ✅
Enable "Allow merge commits" ✅ (needed for releases)
Disable "Allow rebase merging" ❌ (optional)
Set "Squash merging" as the default for the repository

🏷️ Issue Labels

ThemisDB uses a comprehensive labeling system to categorize and organize issues and pull requests.

Quick Reference:

Label Category	Purpose	Examples
Priority	Urgency level	`priority:P0` (critical), `priority:P1` (high)
Type	Issue nature	`type:bug`, `type:feature`, `type:enhancement`
Area	Component affected	`area:llm`, `area:storage`, `area:api`
Status	Current state	`status:ready`, `status:in-progress`
Effort	Work required	`effort:small` (<1 day), `effort:large` (1-2 weeks)
Experience	Contributor level	`good first issue`, `help wanted`

For issue reporters: Don't worry about adding labels - maintainers will add appropriate labels during triage.

For contributors: Look for good first issue labels if you're new to the project.

Complete documentation:

Full Guide: .github/LABELS_GUIDE.md (English & German)
Quick Reference: .github/LABELS_QUICK_REF.md
Label Definitions: .github/labels.yml

Reporting Bugs

Before submitting a bug report:

Check existing issues: Search for similar reports
Verify it's a bug: Ensure it's not expected behavior
Test on latest version: Bug may already be fixed

Bug report template:

## Description
Clear description of the bug

## Steps to Reproduce
1. Step one
2. Step two
3. ...

## Expected Behavior
What you expected to happen

## Actual Behavior
What actually happened

## Environment
- OS: [e.g., Ubuntu 22.04, Windows 11]
- Compiler: [e.g., GCC 11.2, MSVC 2022]
- ThemisDB version/commit: [e.g., v1.0.0 or commit hash]

## Additional Context
Logs, screenshots, or other relevant information

Feature Requests

Feature request template:

## Feature Description
Clear description of the proposed feature

## Motivation
Why is this feature needed? What problem does it solve?

## Proposed Solution
How should this feature work?

## Alternatives Considered
Other approaches you've thought about

## Additional Context
Any other relevant information

Documentation

ThemisDB follows a Living Documentation approach where documentation evolves with the codebase through continuous review and improvement.

Documentation Structure

Architecture docs: docs/architecture/
API docs: docs/api/
User guides: docs/
Examples: examples/
Compendium: compendium/
Translations: docs/de/, docs/fr/, docs/es/, docs/ja/
Archived docs: docs/ARCHIVED/ - Historical development documents (GAP analyses, old roadmaps, completed implementations)

Note: Historical development documents (GAP analyses, roadmaps, TODO lists, implementation summaries) have been archived to docs/ARCHIVED/. See docs/ARCHIVED/README.md for the complete archive index.

Documentation Requirements

All PRs with code changes must include documentation updates:

Complete the PR Documentation Checklist
Update affected documentation files
Add/update code examples if applicable
Update CHANGELOG.md
Ensure documentation builds successfully (mkdocs build --strict)

Documentation must be:

Accurate - Reflects current implementation
Complete - Covers all features and use cases
Clear - Easy to understand for target audience
Tested - Code examples compile and run
Maintained - Regularly reviewed and updated

Continuous Review Process

Documentation is reviewed at multiple levels:

PR Review (Every PR with code changes)
- Documentation changes reviewed alongside code
- At least one reviewer verifies accuracy
- Must pass before merge
Monthly Reviews (First Monday of each month)
- Quick check of recent changes
- Identify and fix quick wins
- Track documentation debt
Quarterly Reviews (Start of each quarter)
- Comprehensive documentation audit
- Test all examples
- Update translations
- Archive outdated content
Release Reviews (Before each release)
- Verify release documentation
- Update version references
- Validate migration guides

Review schedule and process: docs/DOCUMENTATION_REVIEW_SCHEDULE.md

Documentation Guidelines

Writing style:

Use active voice ("Configure the database..." not "The database can be configured...")
Be specific with values and examples
Provide working code examples
Explain prerequisites clearly
Keep language clear and concise

Quality standards:

# Before submitting PR:
mkdocs build --strict              # Verify build
./scripts/check-links.sh           # Validate links
./scripts/test-examples.sh         # Test examples (if available)

Complete documentation guidelines: docs/DOCUMENTATION_REVIEW_GUIDELINES.md

Documentation Archival

ThemisDB preserves outdated documentation in archives to maintain historical context while keeping active documentation current.

Archive documentation when:

Content is outdated and superseded by newer documentation
Feature/component no longer exists or has been replaced
Information has been consolidated into another document
Content is no longer accurate or relevant to current versions
Implementation summaries from completed work (keep for reference)

Archive structure:

Language-agnostic: docs/archive/
Language-specific: docs/{LANG}/archive/ (e.g., docs/de/archive/)

Archival process:

Review - Verify document should be archived
Preserve - Extract valuable content to current docs
Archive - Move with git mv (preserves history)
Annotate - Add archive note using template
Update - Fix all references and update indexes
Document - Update CHANGELOG and archive README

Resources:

Process Guide: docs/DOCUMENTATION_ARCHIVAL_PROCESS.md
Archive Template: docs/archive/ARCHIVE_NOTE_TEMPLATE.md
Archive Indexes: docs/archive/, docs/de/archive/

Key principles:

✅ Always use git mv to preserve history
✅ Add archive note explaining why and when
✅ Update all references to prevent broken links
✅ Document archival in CHANGELOG
✅ Keep archive READMEs organized and current

Package Maintenance

If you're interested in maintaining ThemisDB packages for a specific distribution:

Becoming a Package Maintainer

We welcome package maintainers for all platforms! To become a maintainer:

Review the packaging documentation:
- Read docs/packaging.md for detailed instructions
- Check docs/PACKAGING-QUICKREF.md for quick reference
Test the package build:
- Build the package for your target platform
- Install and test in a clean environment
- Verify all functionality works as expected
Submit to distribution repositories:
- Follow platform-specific guidelines (see docs/packaging.md)
- Submit package to appropriate repository (PPA, AUR, Copr, etc.)
- Notify us via GitHub issue when package is published
Keep packages updated:
- Monitor releases and security updates
- Update packages within 1-2 weeks of new releases
- Coordinate with core team for pre-release testing

Supported Platforms

We currently support packaging for:

Automation Tools

Use the provided scripts to prepare new releases:

# Linux/macOS
./scripts/prepare-release.sh 1.0.1

# Windows
.\scripts\prepare-release.ps1 -Version 1.0.1

These scripts automatically update version numbers across all packaging files.

Package Maintainer Benefits

Questions?

License

By contributing to ThemisDB, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to ThemisDB! 🚀

🚀 Release Process

ThemisDB uses a tag-based release strategy with semantic versioning. Releases are automated through GitHub Actions when version tags are pushed.

Branching Strategy Overview

Important

ThemisDB Git Flow:

develop = Default branch for active development (integration)
main = Protected production branch (releases only)
feature/* = Feature branches (from/to develop)
bugfix/* = Bug fix branches (from/to develop)
release/* = Release preparation branches (from develop to main)
hotfix/* = Emergency fixes (from/to main, then back to develop)

Release Flow

feature branches → develop → release branch → main → tag → GitHub Release
                      ↑                         ↓
                      └─────── merge back ──────┘

Creating a Release

1️⃣ Prepare Release Branch

# Branch from develop for release preparation
git checkout develop
git pull origin develop
git checkout -b release/v1.4.0

# Update VERSION file
echo "1.4.0" > VERSION

# Update CHANGELOG.md
# Add release notes under ## [1.4.0] - YYYY-MM-DD

# Commit version updates
git add VERSION CHANGELOG.md
git commit -m "chore(release): Prepare version 1.4.0"
git push origin release/v1.4.0

2️⃣ Create PR to Main

Create a Pull Request from release/v1.4.0 to main
PR title: "Release v1.4.0"
Required checks must pass:
- ✅ Build & Test (Ubuntu, Windows, macOS)
- ✅ Security scan
- ✅ Code quality checks
Get approval from maintainer
Merge using merge commit (not squash)

3️⃣ Create and Push Tag

# After PR is merged to main
git checkout main
git pull origin main

# Create annotated tag with release notes
git tag -a v1.4.0 -m "Release v1.4.0

- Feature 1: Description
- Feature 2: Description
- Bug fix: Description

See CHANGELOG.md for full details."

# Push tag to trigger release workflow
git push origin v1.4.0

[!NOTE] The tag push automatically triggers the release workflow which:

Builds release binaries for Ubuntu, Windows, and macOS

Creates a GitHub Release

Uploads artifacts (.tar.gz, .deb, .zip)

Generates release notes from commits and CHANGELOG.md

4️⃣ Merge Back to Develop

# Keep develop in sync with main
git checkout develop
git pull origin develop
git merge main -m "chore: Merge release v1.4.0 back to develop"
git push origin develop

Version Numbering

ThemisDB follows Semantic Versioning 2.0.0 (semver.org):

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples:
- 1.4.0         (stable release)
- 1.4.0-alpha   (alpha pre-release)
- 1.4.0-beta.1  (beta pre-release)
- 1.4.0-rc.1    (release candidate)
- 1.4.0+build.1 (build metadata)

Version Increment Rules:

Version	When to Increment	Example
MAJOR	Breaking changes to API/behavior	1.4.0 → 2.0.0
MINOR	New features (backward compatible)	1.4.0 → 1.5.0
PATCH	Bug fixes (backward compatible)	1.4.0 → 1.4.1

Hotfix Process

For critical production issues that need immediate release:

Hotfix Workflow

# 1. Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/v1.4.1

# 2. Fix the issue
# ... make changes ...

# 3. Update VERSION and CHANGELOG
echo "1.4.1" > VERSION
# Update CHANGELOG.md with hotfix notes

# 4. Commit and push
git add .
git commit -m "fix: Critical security issue in authentication"
git push origin hotfix/v1.4.1

# 5. Create PR to main (fast-track approval)
# Merge after required checks pass

# 6. Tag the hotfix release
git checkout main
git pull origin main
git tag -a v1.4.1 -m "Hotfix v1.4.1: Security patch"
git push origin v1.4.1

# 7. Merge back to develop
git checkout develop
git pull origin develop
git merge main -m "chore: Merge hotfix v1.4.1 to develop"
git push origin develop

Pre-Release Process

For alpha, beta, or release candidate versions:

# Example: Create beta release
echo "1.5.0-beta.1" > VERSION

# Tag with pre-release label
git tag -a v1.5.0-beta.1 -m "Beta release v1.5.0-beta.1"
git push origin v1.5.0-beta.1

Note

Pre-release tags (containing - like v1.5.0-beta.1) are automatically marked as pre-release in GitHub Releases.

Release Checklist

Use this checklist when preparing a release:

Status Check Requirements

Branch	Required Checks	Optional Checks
develop	Ubuntu build & test	Windows, macOS
main	All platforms (Ubuntu, Windows, macOS)	Security scan

Automated Release Workflow

When you push a version tag (e.g., v1.4.0), the release workflow automatically:

✅ Validates version tag matches VERSION file
🔨 Builds release binaries for:
- Ubuntu (.tar.gz, .deb)
- Windows (.zip)
- macOS (.tar.gz)
📦 Packages all binaries with CPack
📝 Generates release notes from CHANGELOG.md and commits
🚀 Creates GitHub Release with all artifacts
📢 Publishes release (or marks as pre-release)

Monitoring Releases

GitHub Actions: Actions Tab
Releases: Releases Page
Tags: Tags List

📦 Package Maintenance

Interested in maintaining ThemisDB packages for your platform?
We welcome package maintainers for all distributions!

Becoming a Package Maintainer

1️⃣ Review Packaging Documentation

📖 Read docs/packaging.md for detailed instructions
📄 Check docs/PACKAGING-QUICKREF.md for quick reference

2️⃣ Test Package Build

🔨 Build the package for your target platform
🧪 Install and test in a clean environment
✅ Verify all functionality works as expected

3️⃣ Submit to Distribution Repositories

📝 Follow platform-specific guidelines
📤 Submit package to appropriate repository (PPA, AUR, Copr, etc.)
📣 Notify us via GitHub issue when package is published

4️⃣ Keep Packages Updated

👀 Monitor releases and security updates
⚡ Update packages within 1-2 weeks of new releases
🤝 Coordinate with core team for pre-release testing

Supported Platforms

Platform	Package Format	Repository
🐧 Linux	`.deb`, `.rpm`, `PKGBUILD`	Debian/Ubuntu, Fedora/RHEL, Arch
🪟 Windows	Chocolatey, WinGet	chocolatey.org
🍎 macOS	Homebrew Formula	brew.sh

Automation Tools

Use provided scripts to prepare new releases:

# Linux/macOS
./scripts/prepare-release.sh 1.0.1

# Windows
.\scripts\prepare-release.ps1 -Version 1.0.1

Note

These scripts automatically update version numbers across all packaging files.

Package Maintainer Benefits

🏆 Listed as package maintainer in README
🚀 Early access to release candidates for testing
💬 Direct communication channel with core team
🎉 Recognition in release notes

❓ Questions?

Resource	Purpose	Link
💬 GitHub Discussions	General questions	Discussions
🐛 GitHub Issues	Bug reports & features	Issues
📚 Documentation	Detailed guides	docs/

📄 License

By contributing to ThemisDB, you agree that your contributions will be licensed under the MIT License.

🙏 Thank you for contributing to ThemisDB!

⭐ Star us on GitHub · 📖 Read the Docs · 💬 Join Discussions

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to ThemisDB

Table of Contents

🤝 Contributing to ThemisDB

📋 Table of Contents

🤝 Code of Conduct

Getting Started

Prerequisites

Development Environment Setup

🚀 Getting Started

Prerequisites

Development Environment Setup

Install Code Quality Tools

Development Workflow

1. Create a Feature Branch

2. Make Your Changes

3. Run Code Quality Checks

4. Commit Your Changes

5. Push and Create Pull Request

💻 Development Workflow

1️⃣ Create a Feature Branch

2️⃣ Make Your Changes

3️⃣ Run Code Quality Checks

4️⃣ Commit Your Changes

5️⃣ Push and Create Pull Request

Code Quality Standards

Static Analysis (clang-tidy)

Linting (cppcheck)

Code Coverage

Secret Scanning (Gitleaks)

Code Style

Comments:

✅ Code Quality Standards

🔍 Static Analysis (clang-tidy)

🧪 Linting (cppcheck)

📊 Code Coverage

🔐 Secret Scanning (Gitleaks)

📋 License Compliance

🎨 Code Style

Pull Request Process

Before Submitting

PR Description Template

PR Description Template

Review Process

Merge Strategy Guidelines

🏷️ Issue Labels

Reporting Bugs

Feature Requests

Documentation

Documentation Structure

Documentation Requirements

Continuous Review Process

Documentation Guidelines

Documentation Archival

Package Maintenance

Becoming a Package Maintainer

Supported Platforms

Automation Tools

Package Maintainer Benefits

Questions?

License

Thank you for contributing to ThemisDB! 🚀

🚀 Release Process

Branching Strategy Overview

Release Flow

Creating a Release

Version Numbering

Hotfix Process

Pre-Release Process

Release Checklist

Status Check Requirements

Automated Release Workflow

Monitoring Releases

📦 Package Maintenance

Becoming a Package Maintainer