Add release procedure and automation gates

.dockerignore

@@ -8,10 +8,21 @@ config.log
 config.status
 configure
 Makefile
-src/.deps
+doc/Makefile
+doc/latex_manuals/Makefile
+man/Makefile
+specfiles/Makefile
+specfiles/bulk_extractor.fedora.spec
+specfiles/bulk_extractor.opensuse.spec
+specfiles/bulk_extractor.spec.m4
 src/.libs
+src/.deps
 src/Makefile
 src/*.o
 src/bulk_extractor
 src/test_*
+src/tests/Makefile
+tests/Makefile
+bulk_extractor-*
+release-artifacts
 win64

.github/ISSUE_TEMPLATE/release.yml

@@ -0,0 +1,97 @@
+name: Release
+description: Plan, validate, and publish a versioned bulk_extractor release.
+title: "release: "
+labels: [release]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this issue as the release record. Do not attach forensic images, unredacted scan output, credentials, presigned URLs, or other sensitive material. Record only approved image identifiers/checksums and redacted validation evidence.
+  - type: input
+    id: version
+    attributes:
+      label: Target version
+      description: The intended release version, for example `2.2.1`.
+      placeholder: "2.2.1"
+    validations:
+      required: true
+  - type: input
+    id: tag
+    attributes:
+      label: Release tag
+      description: Immutable signed annotated tag to create after release-PR merge.
+      placeholder: "v2.2.1"
+    validations:
+      required: true
+  - type: input
+    id: commit
+    attributes:
+      label: Reviewed commit SHA
+      description: Full SHA at which the tag will be created. Do not use a mutable branch name.
+      placeholder: "0123456789abcdef..."
+    validations:
+      required: true
+  - type: textarea
+    id: people
+    attributes:
+      label: Release manager and package maintainers
+      description: Name the release manager and the maintainers authorized to submit Debian and RPM packages.
+      placeholder: |
+        Release manager: @...
+        Debian repository maintainer: @...
+        RPM repository maintainer: @...
+    validations:
+      required: true
+  - type: textarea
+    id: large_images
+    attributes:
+      label: Approved large-image validation inputs
+      description: Record only a safe image identifier, SHA-256 checksum, approval source, and storage/access policy. Never attach or link case data.
+      placeholder: |
+        Identifier: ...
+        SHA-256: ...
+        Approval: ...
+        Access policy: ...
+    validations:
+      required: true
+  - type: textarea
+    id: build_evidence
+    attributes:
+      label: Build and validation evidence
+      description: Add URLs for macOS, Ubuntu, Fedora/RPM, Windows, and AWS validation jobs as they complete. Include redacted result summaries and checksums only.
+      placeholder: |
+        - [ ] macOS `make distcheck`:
+        - [ ] macOS large-image scan:
+        - [ ] Ubuntu `make distcheck`:
+        - [ ] Fedora/RPM `make distcheck`:
+        - [ ] Windows executable and Unicode test:
+        - [ ] AWS large-image validation and cleanup:
+    validations:
+      required: true
+  - type: textarea
+    id: artifacts
+    attributes:
+      label: Release artifacts and provenance
+      description: Add each artifact filename, SHA-256 checksum, producing job URL, and eventual publication URL.
+      placeholder: |
+        - [ ] Source archive:
+        - [ ] Windows executable:
+        - [ ] Debian package:
+        - [ ] RPM package:
+        - [ ] AWS validation summary:
+        - [ ] SHA256SUMS:
+    validations:
+      required: true
+  - type: checkboxes
+    id: gates
+    attributes:
+      label: Release gates
+      options:
+        - label: The release PR updates `configure.ac`, release notes, and applicable package metadata.
+          required: true
+        - label: The tag will be signed, annotated, immutable, and created at the reviewed SHA only after all required checks pass.
+          required: true
+        - label: I will use a draft GitHub Release and publish it only after the evidence and artifacts are reviewed.
+          required: true
+        - label: I will not include confidential forensic data or credentials in this issue.
+          required: true

.github/workflows/ci-cd.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches: [main]
   pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
     paths-ignore:
       - '**.md'
       - 'AGENTS.md'
@@ -18,6 +19,7 @@ permissions:
 
 jobs:
   debian:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     name: Debian Bookworm build
     runs-on: ubuntu-latest
 
@@ -49,6 +51,7 @@ jobs:
             '
 
   build:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     name: build and test (${{ matrix.os }})
     strategy:
       fail-fast: false

.github/workflows/codecov.yml

@@ -6,6 +6,7 @@ on:
   push:
     branches: [main]
   pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
     paths-ignore:
       - '**.md'
       - 'AGENTS.md'
@@ -20,6 +21,7 @@ permissions:
 
 jobs:
   build:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     name: build and test
     runs-on: ubuntu-22.04
 

.github/workflows/latex-docs.yml

@@ -2,6 +2,7 @@ name: Build and publish LaTeX documentation
 
 on:
   pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
     paths:
       - 'doc/**/*.tex'
       - '.github/workflows/latex-docs.yml'
@@ -23,6 +24,7 @@ concurrency:
 
 jobs:
   build:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

.github/workflows/mingw.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches: [main]
   pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
     paths-ignore:
       - '**.md'
       - 'AGENTS.md'
@@ -22,6 +23,7 @@ env:
 
 jobs:
   mingw:
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     name: Ubuntu MinGW executable
     runs-on: ubuntu-24.04
 

AGENTS.md

@@ -2,8 +2,19 @@
 
 GitHub activity authored by Codex must use `@${USER}-codex` when that account exists. For this workspace, use `@simsong-codex`; do not use the personal `@simsong` identity for GitHub writes, pushes, issues, pull requests, reviews, or comments.
 
+Before creating or amending a Codex-authored commit, configure and verify this
+repository's author and committer as `Codex AI Assistant <simsong+codex@acm.org>`
+and verify the configured signing key belongs to that identity. SSH remote
+authentication (including `github-codex`) controls push access only; it does
+not set commit metadata. Use `git log --format='%G? %GS %an <%ae> %cn <%ce>'`
+to verify the resulting commit before pushing. When correcting existing
+commits, use `git commit --amend --reset-author -S` rather than only amending
+the signature.
+
 For every Codex-authored pull request, request a Copilot review after publishing it by requesting `copilot-pull-request-reviewer` (not `copilot`). Verify the request through GitHub's review state, then monitor until a Copilot review or review thread actually appears and all required CI checks have completed. Do not report a request as made, or Copilot as having responded, based only on a CLI command or an `@copilot` comment. Address actionable feedback before declaring the pull request ready. When pushing a fix in response to Copilot, reply to its thread with the fix and validation evidence, but leave the thread unresolved for `@simsong` to review and resolve. Once it is green and feedback-free, mark it ready for review and assign it to `@simsong`; do not approve or merge it unless explicitly asked.
 
+Delete a local branch once it has merged into `main`. First verify that it is an ancestor of the current `main`; preserve unmerged branches and local files in linked worktrees.
+
 Do not close GitHub issues. You may validate an issue, record evidence, and recommend closure in a comment, but change an issue's open/closed state only when the repository owner explicitly instructs you to do so.
 
 Before changing a scanner or writing a scanner plug-in, read

Makefile.am

@@ -21,6 +21,9 @@ SUBDIRS = doc doc/latex_manuals man src src/tests specfiles tests
 include Makefile.auto_defs
 
 EXTRA_DIST = $(SRC_WIN_DIST) $(AUTO_DOC_FILES) $(AUTO_ETC_FILES) $(AUTO_LICENSES) \
+	$(srcdir)/etc/Dockerfile.fedora-distcheck \
+	$(srcdir)/etc/Dockerfile.ubuntu-distcheck \
+	$(srcdir)/scripts/release.sh \
 	$(srcdir)/AGENTS.md \
 	$(srcdir)/.gitignore \
 	$(srcdir)/CODING_STANDARDS.md \
@@ -88,3 +91,32 @@ libinstall:
 	install -D src/libbulkextractor.so $(prefix)/lib/libbulkextractor.so
 	install -D python/module/bulkextractor.py $(prefix)/lib/python2.7/dist-packages/bulkextractor.py
 	if [ -r /sbin/ldconfig ]; /sbin/ldconfig -v ; fi
+
+# Release orchestration is deliberately fail-closed and isolated from the
+# active checkout. See scripts/release.sh and doc/RELEASE_PROCEDURE.md.
+RELEASE_ARTIFACT_DIR ?= $(abs_builddir)/release-artifacts
+RELEASE_SCRIPT = $(abs_srcdir)/scripts/release.sh
+
+.PHONY: release
+release:
+	RELEASE_ARTIFACT_DIR="$(RELEASE_ARTIFACT_DIR)" RELEASE_SOURCE_DIR="$(abs_srcdir)" "$(RELEASE_SCRIPT)"
+
+# Each Finch build copies a clean source context and runs the real distcheck
+# inside it. Finch selects native arm64 and emulated amd64 on Apple Silicon.
+CONTAINER_ENGINE ?= finch
+CONTAINER_PLATFORMS ?= arm64 amd64
+
+.PHONY: distcheck-ubuntu-container distcheck-fedora-container distcheck-containers
+distcheck-ubuntu-container:
+	@set -e; for platform in $(CONTAINER_PLATFORMS); do \
+		$(CONTAINER_ENGINE) build --platform "$$platform" --progress=plain \
+			--file etc/Dockerfile.ubuntu-distcheck .; \
+	done
+
+distcheck-fedora-container:
+	@set -e; for platform in $(CONTAINER_PLATFORMS); do \
+		$(CONTAINER_ENGINE) build --platform "$$platform" --progress=plain \
+			--file etc/Dockerfile.fedora-distcheck .; \
+	done
+
+distcheck-containers: distcheck-ubuntu-container distcheck-fedora-container

doc/RELEASE_NOTES.md

@@ -7,6 +7,10 @@ not exhaustive changelogs. Some legacy announcement dates disagree with tag
 dates; the version history below therefore uses dates only where the repository
 history is clear.
 
+The historical roadmaps were planning documents, not release records. Their
+relevant context is incorporated below; preserved, commit-specific copies are
+linked from the [historical source map](#historical-source-map).
+
 ## 2.2.0 (draft)
 
 **Status:** Unreleased. The source version is currently
@@ -212,6 +216,19 @@ through the project's normal pull-request and CI process.
   ([PR #561](https://github.com/simsong/bulk_extractor/pull/561),
   [PR #558](https://github.com/simsong/bulk_extractor/pull/558),
   [PR #557](https://github.com/simsong/bulk_extractor/pull/557)).
+- Rewrote the installed `bulk_extractor(1)` manual for the 2.2 command-line
+  interface, current logging, scanner controls, and supported documentation.
+- Removed the unmaintained standalone HTML overview; the current LaTeX guide
+  and published documentation site are the supported user documentation.
+- Removed the unmaintained version-1 performance notebook with obsolete
+  benchmarks, platforms, and SQL tuning guidance.
+- Documented a controlled release procedure and release-issue template, with
+  isolated artifact assembly, macOS and container `distcheck` gates, and
+  source-level downstream submission paths for Debian/Kali and
+  Fedora/openSUSE ([#621](https://github.com/simsong/bulk_extractor/issues/621),
+  [#622](https://github.com/simsong/bulk_extractor/issues/622),
+  [#623](https://github.com/simsong/bulk_extractor/issues/623),
+  [#626](https://github.com/simsong/bulk_extractor/issues/626)).
 
 ### Known limitations and release work
 
@@ -264,9 +281,10 @@ and production-oriented defaults replaced the broader experimental posture of
 version 1.
 
 The rewrite also reorganized scanner and feature-recorder APIs, improved DFXML
-reporting and testability, and introduced the initial version-2 E01 path. See
-the contemporary [2.0 roadmap](ROADMAP_2.0.md) for the design goals; it is a
-planning record rather than a final release announcement.
+reporting and testability, and introduced the initial version-2 E01 path. Its
+planning record proposed C++14, continuous integration, systematic unit and
+end-to-end tests, and a narrower command-line distribution. It also identified
+future scanner and carving work that was not a release commitment.
 
 ### Maintenance through 2.0.3
 
@@ -301,6 +319,8 @@ placement for the 64-bit executable was corrected.
 The surviving [1.6.0 announcement](announce/announce_1.6.0.md) is explicitly a
 pre-release draft. This summary combines it with the repository `ChangeLog` and
 tagged source rather than treating that draft as a final historical record.
+The contemporary roadmap also recorded longer-term work on scanner development,
+carving, testing, and BEViewer; those proposals were not commitments for 1.6.0.
 
 ### 1.5.x
 
@@ -317,7 +337,9 @@ Encryption, added RFC 4648 Base64 handling, and introduced the MSXML scanner for
 Microsoft Office Open XML documents.
 
 See the original [1.5 announcement](announce/announce_1.5.md) and
-[1.5.2 notes](announce/announce_1.5.2.md).
+[1.5.2 notes](announce/announce_1.5.2.md). The associated roadmap carried
+forward proposals for future scanners, carvers, testing, and user-interface
+work; it does not define the shipped 1.5.x scope.
 
 ### 1.4.x
 
@@ -336,15 +358,20 @@ Command-line compatibility changed: block size and word-size controls moved from
 refactored.
 
 See the original [1.4 announcement](announce/announce_1.4.txt) and
-[1.4.1 notes](announce/announce_1.4.1.txt).
+[1.4.1 notes](announce/announce_1.4.1.txt). The associated roadmap recorded
+planned scanner, raw-device, restart, and validation work, including proposals
+deferred to later releases.
 
 ## Historical source map
 
 - [`ChangeLog`](../ChangeLog) records selected changes from the version-1 and
   version-2 development periods.
 - [`doc/announce`](announce/) contains announcements for 1.2, 1.3, 1.3.1, 1.4,
   1.4.1, 1.5, 1.5.2, 1.6.0, and 2.1.0.
-- [`doc/ROADMAP_2.0.md`](ROADMAP_2.0.md) records the goals and migration plan for
-  the version-2 rewrite.
+- The original planning records are preserved at the commit that last contained
+  them: [1.4 roadmap](https://github.com/simsong/bulk_extractor/blob/d79d91bfee1a601189045a3dfa873b9c3086b493/doc/ROADMAP_1.4.md),
+  [1.5 roadmap](https://github.com/simsong/bulk_extractor/blob/d79d91bfee1a601189045a3dfa873b9c3086b493/doc/ROADMAP_1.5.md),
+  [1.6 roadmap](https://github.com/simsong/bulk_extractor/blob/d79d91bfee1a601189045a3dfa873b9c3086b493/doc/ROADMAP_1.6.md),
+  and [2.0 roadmap](https://github.com/simsong/bulk_extractor/blob/d79d91bfee1a601189045a3dfa873b9c3086b493/doc/ROADMAP_2.0.md).
 - Git tags and their trees remain the authoritative source for the exact code in
   each release.