Release Process

Release Process

A release is complete only after a comprehensively tested commit is published from main and its administrative closeout is finished.

Governing policy

This page is the authoritative release process for OSINT Forge. The numbered sections are sequential release gates: complete and verify each step in order before beginning the next. Steps may not be skipped, combined, reordered, or treated as complete while required checks remain pending.

If this process is revised, the newest published revision governs subsequent release work. Any exception must be documented in the release tracker before publication. All AI participation is governed by AI Development Policy, and project authority and policy precedence are defined in Governance and Maintainer Authority.

1. Open a release tracker

Create an issue containing every release gate: implementation audit, tests, supported platforms, Python matrix, ShellCheck, plugin contracts, lifecycle dry-runs, documentation audit, version, changelog, merge, live VM validation, patch-and-retest loop, tag, publication, publication verification, release announcement, repository documentation, wiki updates, and administrative closeout.

Identify every repository document and wiki page affected by the release so none are omitted later.

2. Prepare a release candidate

• Audit all changed behavior and repository contents.
• Fix defects and add regression tests.
• Replace the development version with the final version.
• Finalize the versioned changelog and draft release notes.
• Update repository documentation needed to test and accurately describe the candidate.
• Confirm source-archive hygiene and executable modes.
• Keep the candidate on a focused branch and open a draft pull request.

Do not prematurely identify an unreleased candidate as the latest stable version. Stable-version references and final wiki guidance are completed after publication.

3. Validate comprehensively

./scripts/dev-check.sh
osint forge validate --json
osint --version

Run all seven GitHub Actions jobs, plugin lifecycle dry-runs, clean installation, upgrade replacement, uninstall preservation, Markdown links, shell syntax, archive extraction, version checks, and credential-pattern scans. Exercise the documented synthetic workflow end to end.

4. Merge

Mark the pull request ready only after local and hosted checks pass. Merge into main and record the exact merge commit. A merged release-preparation pull request is not a published release.

5. Validate on a live Debian VM

After the candidate is merged into main, but before tagging or publishing, test that exact commit on a VM running a current stable Debian release. The standard autonomous entrypoint is ./scripts/codex-qa.sh release; use status or attach to monitor the persistent session without disturbing its evidence.

LizardPope1101 selects and authorizes one of two valid operating modes:

Human-operated mode

1. The AI reviews the release scope and devises comprehensive tests covering installation, upgrade behavior, commands, plugins, workflows, output, permissions, failure handling, resumability, reporting, and all changed functionality.
2. The AI furnishes commands in controlled, reviewable blocks.
3. The human operator runs those commands in the VM.
4. The human returns complete command output and relevant logs to the AI.
5. The AI reviews the evidence, identifies defects or gaps, and determines the next test or corrective action.

Owner-authorized autonomous mode

1. LizardPope1101 explicitly authorizes an AI to operate the dedicated testing VM and defines its repository, VM, testing, patching, merge, release, and closeout scope.
2. The AI records the authorization boundary, release scope, Debian version, starting commit, installed stable version, credentials state, and environment before changing anything.
3. The AI executes the complete live test plan directly, preserving commands, timestamps, versions, output, exit codes, defects, patches, reruns, and conclusions as reviewable evidence.
4. The AI stops and classifies the release as blocked or not released if access is missing, a gate fails, material uncertainty remains, or an action exceeds its authorization.
5. The AI may patch, open and merge focused pull requests, retest, tag, publish, and complete administrative closeout only when those actions were expressly authorized and every preceding gate has passed.

Autonomous mode does not allow an AI to change or reinterpret the policies governing its own authority. It does not reduce the test scope or permit unattended use of real third-party personal data.

In either mode, use synthetic targets, reserved example domains, operator-owned accounts and files, loopback or explicitly authorized infrastructure, and non-sensitive data. Record the Debian version, tested commit, framework version, plugin versions, commands, timestamps, exit codes, results, defects, patches, reruns, and retained logs in the release tracker. Store local QA evidence with owner-only permissions.

If testing exposes a defect, stop the release. Create and merge corrective patches into main, rerun full automated validation, update the VM to the new commit, and repeat affected live tests plus the complete release smoke test. Continue until no release-blocking defects remain. Record the exact validated commit; only that commit may be tagged.

6. Tag and publish

Create the semantic version tag at the verified commit, for example vX.Y.Z. Publish a non-prerelease GitHub Release, mark it latest, and provide accurate highlights, installation commands, safety language, and complete code fences. GitHub supplies source ZIP and tarball downloads.

7. Verify publication

• Confirm the release is public, latest, and not a draft or prerelease.
• Confirm the tag is identical to the live-tested commit.
• Read the version directly from tagged source.
• Verify the title, body, links, code fences, ZIP, and tarball.
• Verify installation or upgrade from the published tag on the supported Debian environment.

Do not close the release tracker yet. Publication verification is followed by mandatory administrative closeout.

8. Complete administrative closeout

1. Announce the release in GitHub Discussions. Publish in the Announcements category with a high-level overview of the release, its major features or fixes, important compatibility or safety notes, installation or upgrade guidance when useful, a link to the GitHub Release, and a direct link to the versioned changelog.
2. Update all applicable repository documentation. Audit the README, changelog, release guidance, command and workflow documentation, architecture and API contracts, security, governance, contribution guidance, roadmap, examples, and other affected documents. Ensure they describe the released behavior, identify the correct stable version, and contain no stale development-only claims.
3. Update all applicable wiki pages. Audit the Home page, Roadmap, Installation, Command Reference, Case Management, Batch Workflows, Plugin Catalog, Plugin Development, Architecture, Development and CI, Troubleshooting, Security and Ethics, administrative policies, and any other affected page. Update every applicable area to match the released version.
4. Verify the administrative state. Check the rendered Discussion announcement, changelog and release links, repository documentation links and examples, wiki navigation and internal links, stable-version references, and consistency among the tag, GitHub Release, repository documents, and wiki.
5. Record and close. Add the announcement link and documentation-verification results to the release tracker. Close the release tracker only after every prior gate and every closeout item is complete.

Administrative closeout is a release requirement, not optional publicity or deferred housekeeping. A published release with incomplete closeout remains an open release process.

OSINT Forge follows semantic versioning. Until v1.0, minor versions may include breaking changes. See Roadmap and the changelog.