Version Management and Release Process

Relevant source files

• .github/workflows/mkdocs.yml
• .github/workflows/python-package.yml
• mineru/version.py
• update_version.py

Purpose and Scope

This document describes MinerU's version management system and automated release process. It covers how version numbers are tracked, the Git tag-based versioning scheme, the CI/CD pipeline for publishing releases, and the automation that deploys packages to PyPI and GitHub Releases. For information about continuous testing workflows, see CI/CD Pipeline and Workflows. For documentation deployment, see Documentation System (MkDocs).

Sources: .github/workflows/python-package.yml1-145 mineru/version.py1-2 update_version.py1-28

---

Version Storage and Tracking

MinerU uses a single-source-of-truth approach for version management. The canonical version number is stored in `mineru/version.py`() as a simple __version__ string variable:

This version file serves multiple purposes:

• Package metadata: Used by pyproject.toml to set the distribution version
• Runtime version reporting: Accessible to the application and users via mineru.__version__
• Release automation: Updated automatically during the release process

The version number follows semantic versioning principles (MAJOR.MINOR.PATCH) and is automatically synchronized with Git tags during the release workflow.

Sources: mineru/version.py1-2

---

Git Tag-Based Versioning

Version Extraction Script

The `update_version.py`() script extracts version information from Git tags and updates the version file. It implements the core version management logic:

Function	Purpose	Implementation
get_version()	Extracts version from Git tags	Executes git describe --tags and parses output
write_version_to_commons()	Updates version.py	Writes __version__ = "{version}" to file

Tag Parsing Logic

The `get_version()`() function implements the following algorithm:

1. Execute git describe --tags to get the most recent tag
2. Parse the tag format: expects mineru-<version>-released
3. Extract the version component (second part after splitting on -)
4. Validate format and return version string
5. Fall back to "0.0.0" on error

Example tag parsing:

• Input tag: mineru-2.7.6-released
• Extracted version: 2.7.6

Sources: update_version.py5-28

---

Release Automation Pipeline

Workflow Trigger Mechanisms

The `python-package` workflow is triggered by two events:

Trigger	Condition	Use Case
push.tags	Tags matching *released pattern	Automated production releases
workflow_dispatch	Manual trigger	Emergency releases or testing

When triggered, the workflow operates on the master branch and executes a four-stage pipeline with job dependencies ensuring sequential execution.

Sources: .github/workflows/python-package.yml6-11

Four-Stage Release Pipeline

Sources: .github/workflows/python-package.yml13-145

---

Stage 1: Version Update

The `update-version` job executes on ubuntu-latest and performs version synchronization:

Steps Execution

1. Repository Checkout L18-22: Checks out the master branch with full Git history (fetch-depth: 0) to access all tags
2. Python Setup L24-27: Installs Python 3.10 using actions/setup-python@v6
3. Version Update L29-31: Executes python update_version.py to extract version from Git tag and update `mineru/version.py`()
4. Verification L33-36: Lists and displays the updated version file for audit trail
5. Commit Changes L38-48: Commits changes with author myhloli <[email protected]>, skips if no changes detected
6. Push to Master L50-55: Pushes commit to master branch using RELEASE_TOKEN secret

Git Configuration

The workflow configures Git with hardcoded credentials:

• Author Email: [email protected]
• Author Name: myhloli

This ensures consistent commit attribution across all automated version updates.

Sources: .github/workflows/python-package.yml15-56

---

Stage 2: Installation Verification

The `check-install` job validates package installability across Python versions:

Matrix Strategy

Parameter	Values	Purpose
python-version	["3.10", "3.11", "3.12", "3.13"]	Test all supported Python versions
fail-fast	false	Continue testing even if one version fails

Validation Process

1. Updated Code Checkout L66-70: Fetches master branch after version update commit
2. Version Verification L72-75: Confirms mineru/version.py contains the updated version
3. Python Environment L77-80: Sets up the matrix-specified Python version
4. Installation Test L82-85: Performs editable install with core dependencies: pip install -e .[core]

This stage ensures the updated package is installable before building distribution artifacts. If installation fails on any Python version, the workflow continues but marks the job as failed.

Sources: .github/workflows/python-package.yml57-86

---

Stage 3: Wheel Building

The `build` job creates the distribution package:

Build Configuration

• Python Version: 3.10 (single version, no matrix)
• Build Tools: wheel, build packages
• Output: .whl file in dist/ directory

Build Process

Artifact Management

The wheel file is uploaded as a GitHub Actions artifact with:

• Artifact Name: wheel-file
• Path Pattern: dist/*.whl
• Retention Period: 30 days

This artifact bridges the build and release jobs, allowing the wheel to be downloaded and published in the final stage.

Sources: .github/workflows/python-package.yml87-118

---

Stage 4: Publication

The `release` job publishes the package to two targets:

GitHub Release Creation

Uses `softprops/action-gh-release@4634c16e79c963813287e889244c50009e7f0981` to:

• Create a GitHub Release from the Git tag
• Attach the wheel file from dist/*.whl
• Authenticate with RELEASE_TOKEN secret

PyPI Publication

The PyPI upload process L140-144:

1. Install Tools: twine, keyring, packaging utilities
2. Validation: twine check dist/* validates wheel metadata
3. Upload: twine upload dist/* -u __token__ -p ${{ secrets.PYPI_TOKEN }}

Parameter	Value	Purpose
Username	__token__	PyPI token-based authentication
Password	${{ secrets.PYPI_TOKEN }}	API token from GitHub secrets
Files	dist/*	All distribution files in dist directory

Sources: .github/workflows/python-package.yml119-145

---

Tag Naming Convention

Required Format

MinerU releases must follow a strict tag naming pattern:

mineru-<MAJOR>.<MINOR>.<PATCH>-released

Examples:

• mineru-2.7.6-released → Version 2.7.6
• mineru-3.0.0-released → Version 3.0.0

Pattern Components

Component	Description	Validation
mineru-	Project prefix	Required, validated by update_version.py
X.Y.Z	Semantic version	Extracted as version number
-released	Release suffix	Triggers workflow via *released pattern

Workflow Activation

The workflow trigger pattern *released L9 matches any tag ending with "released", but `update_version.py`() enforces the full format by checking if the first part starts with "mineru". Tags not matching this format will cause the version extraction to fail and fall back to "0.0.0".

Sources: .github/workflows/python-package.yml8-9 update_version.py10-13

---

Secrets Configuration

Required GitHub Secrets

MinerU's release process requires two secrets configured in the repository settings:

Secret Name	Usage	Scope
RELEASE_TOKEN	GitHub API authentication	Git push to master, create releases
PYPI_TOKEN	PyPI API authentication	Package upload to PyPI

RELEASE_TOKEN Usage

Used in two contexts:

1. Version Update Commit L50-55:

   • Pushes version update commit to master branch
   • Requires repository write access

2. GitHub Release Creation L134-138:

   • Creates GitHub Release from tag
   • Attaches wheel file as release asset
   • Requires release creation permission

PYPI_TOKEN Usage

The PyPI token L144 must:

• Be a valid PyPI API token (not username/password)
• Have upload permissions for the mineru package
• Be passed to twine with username __token__ (literal string)

Sources: .github/workflows/python-package.yml53-54 .github/workflows/python-package.yml138 .github/workflows/python-package.yml144

---

Release Workflow Execution Flow

Sources: .github/workflows/python-package.yml1-145

---

Related Workflows

Documentation Deployment

The `mkdocs` workflow runs independently from the release process:

Trigger	Branch	Action
Push to master or dev	Specified branch	Deploy docs to GitHub Pages

This workflow:

• Checks out the dev branch (note: configures checkout to dev regardless of push branch)
• Uses mhausenblas/mkdocs-deploy-gh-pages@master action
• Authenticates with RELEASE_TOKEN
• Installs dependencies from /docs/requirements.txt

For detailed documentation system architecture, see Documentation System (MkDocs).

Sources: .github/workflows/mkdocs.yml1-23

---

Manual Release Process

Workflow Dispatch

Maintainers can manually trigger releases without pushing a tag:

1. Navigate to Actions → Python package in GitHub repository
2. Click Run workflow button
3. Select branch (defaults to master)
4. Click Run workflow to start

This invokes the same four-stage pipeline but requires manual tag creation beforehand for version extraction to succeed.

Emergency Release Procedure

For urgent releases:

1. Create and push tag: git tag mineru-X.Y.Z-released && git push origin mineru-X.Y.Z-released
2. Workflow auto-triggers and executes all stages
3. Monitor workflow progress in GitHub Actions tab
4. Verify publication:
   • GitHub Releases: https://github.com/opendatalab/MinerU/releases
   • PyPI: https://pypi.org/project/mineru/

Sources: .github/workflows/python-package.yml10-11

---

Version Update Code Analysis

update_version.py Implementation

Key Implementation Details

Error Handling L14-16:

• Catches all exceptions during Git command execution
• Falls back to version "0.0.0" to prevent build failures
• Prints exception for debugging

File Path Resolution L20:

• Uses os.path.join() for cross-platform compatibility
• Constructs path relative to script location: mineru/version.py

File Writing L21-22:

• Opens file in write mode (overwrites existing content)
• Writes single line: __version__ = "{version}"\n
• Ensures newline termination for POSIX compliance

Sources: update_version.py1-28

---

Pipeline Dependency Chain

The workflow enforces strict job dependencies using the needs keyword:

Dependency Rationale

Stage	Depends On	Reason
check-install	update-version	Must test installation with updated version number
build	check-install	Only build if installation succeeds on all Python versions
release	build	Only publish if wheel builds successfully

If any job fails, downstream jobs are skipped, preventing publication of broken releases.

Sources: .github/workflows/python-package.yml58 .github/workflows/python-package.yml88 .github/workflows/python-package.yml120

---

Artifact Lifecycle

Upload Phase

The build job uploads the wheel artifact L112-117:

Download Phase

The release job downloads the artifact L126-130:

Storage and Retention

• Storage Location: GitHub Actions artifact storage
• Retention Period: 30 days after workflow completion
• Access: Available in workflow run summary for manual inspection

This artifact mechanism decouples build and release, allowing manual intervention if needed before publication.

Sources: .github/workflows/python-package.yml112-130