Transition to v2-Primary Development Model#

CipherSwarm has transitioned from a dual-track (v1/v2) development model to a v2-primary workflow. Previously, development was split between a stable v1 branch and an active v2 rewrite branch. Now, all active development targets v2, with v1 archived for historical reference and backward compatibility. This change streamlines contributions, branch management, and release processes [PR #282].

Branch Naming Conventions and Main Branch Usage#

• The main branch is now the primary branch for v2 development. All new features, fixes, and releases target main [PR #282].
• The legacy v1 codebase is archived in a branch named v1-archive. This branch is retained for historical reference and backward compatibility but is no longer actively maintained [PR #286].
• Feature branches should be named feature/<short-description>, and hotfix branches should use hotfix/<short-description>. Both types branch from main and merge back into main when complete [CONTRIBUTING.md].

Example:

git checkout -b feature/add-new-api
# ... work ...
git rebase main
git checkout main
git merge feature/add-new-api

Archival of v1#

The v1 branch has been archived as v1-archive. No new development occurs on this branch. It remains available for reference and for users who require the legacy stable version. All documentation, templates, and workflow examples now focus exclusively on the main branch and v2 development [PR #282].

Simplified Contribution Process#

The contribution process has been streamlined:

• All contributions (features, fixes, documentation) should target the main branch.
• Contributors should fork the repository, create a feature or hotfix branch from main, and submit a pull request (PR) against main.
• Before merging, feature branches should be rebased onto main to ensure a clean, linear commit history [CONTRIBUTING.md].

PR and Issue Template Updates#

• PR templates have been updated to remove v1/v2 version targeting. Contributors now describe changes and affected components without specifying a version track [PR #282].
• Issue templates now focus on affected components (e.g., Web UI, Agent API, Core Services) rather than version tracks. Environment information, logs, and screenshots are requested for clarity [PR #282].

Handling Feature and Hotfix Branches#

• Feature branches (feature/<short-description>) are used for new features and improvements. They branch from main and are merged back into main after review and testing.
• Hotfix branches (hotfix/<short-description>) are used for urgent fixes to the production codebase. They also branch from main and are merged back into main after validation.
• All branches should follow the conventional commit message format (see below).

Updated GitHub Workflow#

The repository uses Mergify to automate PR queueing, approvals, and merge protections:

• PR Queueing and Approval:
  • Mergify uses 5 author-specific merge queues (dosubot, dependabot-workflows, dependabot, maintainer, external) to handle PRs based on author type and file changes. Each queue has tailored CI requirements:
    • dosubot queue: PRs authored by dosubot[bot] require only the lint check to pass.
    • dependabot-workflows queue: PRs by dependabot[bot] that modify only .github/workflows/** files require only the lint check.
    • dependabot queue: PRs by dependabot[bot] that modify files outside .github/workflows/ require the full CI suite (lint, lint_api, scan_ruby, test, DCO).
    • maintainer queue: PRs by maintainers (unclesp1d3r) require the lgtm label and full CI suite.
    • external queue: PRs from external contributors require an APPROVED review decision and full CI suite.
  • Three queues have automatic entry enabled (dosubot, dependabot-workflows, and dependabot) via auto_merge_conditions in merge protection settings. These automatically add PRs when author and file conditions are met. The maintainer and external queues require manual queueing using the /queue command. PRs labeled do-not-merge are excluded from all queues.
  • Dependabot PRs are automatically approved and queued based on file changes, splitting workflow-only updates from other dependency updates.
  • Dosubot PRs are automatically approved to allow them to proceed through their dedicated queue [PR #720].
• Keeping PRs Up to Date:
  • Mergify automatically updates PRs to keep them in sync with the main branch, provided they are not drafts and do not have conflicts [PR #720].
• Merge Protections:
  • Commit messages must follow the Conventional Commits specification. This is enforced both by pre-commit hooks and by Mergify merge protections.
  • PRs must be no more than 10 commits behind the base branch (main) to be eligible for merging.

The GitHub Actions CI workflow continues to run on pushes and pull requests to main (and develop, if present for legacy reasons). It includes jobs for security scanning, linting (Ruby code and OpenAPI specification), and running tests [CI.yml].

OpenAPI Specification Validation#

The CI pipeline includes validation of the generated OpenAPI/Swagger documentation to ensure it complies with OpenAPI 3.0 standards and prevents documentation drift:

• lint_api CI Job: Runs the vacuum OpenAPI linter to validate swagger/v1/swagger.json against OpenAPI standards.
• Custom Ruleset: Uses vacuum-ruleset.yaml to disable rules that conflict with Rails conventions (e.g., snake_case properties and underscored paths instead of camelCase and kebab-case).
• Local Validation: Developers can run just lint-api to validate the OpenAPI specification locally before submitting a PR.
• Integrated into CI Checks: The ci-check justfile command includes OpenAPI linting as part of the comprehensive pre-merge validation suite.

Protected areas of the repository include: contracts/ (Agent API specifications), alembic/ (database migrations), .cursor/ (AI assistant configuration), and .github/workflows/ (CI workflows). Changes to these areas require explicit permission and may be subject to additional review [PR #281].

The CODEOWNERS file enforces ownership and review requirements for protected paths.

Conventional Commit Enforcement#

• All commit messages must follow the Conventional Commits specification. Examples include feat: add new API endpoint, fix: correct password validation, docs: update README.
• Enforcement is implemented via .gitlint and pre-commit hooks (commitizen) to ensure commit messages are properly formatted and signed off [.gitlint, .pre-commit-config.yaml].

Example commit message:

feat: add support for distributed hash cracking

Git Workflow Diagram#

For further details, refer to the CONTRIBUTING.md and recent pull requests.