{"id":4731,"library":"python-semantic-release","title":"Python Semantic Release","description":"python-semantic-release automates semantic versioning, changelog generation, and project releases for Python projects based on Git commit messages. It integrates with various CI/CD pipelines and supports multiple version control systems and distribution platforms. The current version is 10.5.3, with releases typically following breaking changes or significant feature additions.","status":"active","version":"10.5.3","language":"en","source_language":"en","source_url":"https://github.com/re-semantic-release/python-semantic-release","tags":["semantic-versioning","ci-cd","release-automation","versioning","changelog","git"],"install":[{"cmd":"pip install python-semantic-release","lang":"bash","label":"Install base package"},{"cmd":"pip install 'python-semantic-release[git]'","lang":"bash","label":"Install with Git support"},{"cmd":"pip install 'python-semantic-release[github]'","lang":"bash","label":"Install with GitHub HVCS support"},{"cmd":"pip install 'python-semantic-release[gitlab]'","lang":"bash","label":"Install with GitLab HVCS support"}],"dependencies":[],"imports":[{"note":"This is the primary entry point for the command-line interface. Direct programmatic use via import is uncommon for general usage; most users interact via the 'semantic-release' CLI command.","symbol":"semantic_release.cli.main","correct":"from semantic_release.cli import main"}],"quickstart":{"code":"import subprocess\nimport os\nimport shutil\n\ndef run_semantic_release_demo():\n    # Setup a temporary directory for the demo\n    demo_dir = \"semantic_release_demo\"\n    if os.path.exists(demo_dir):\n        shutil.rmtree(demo_dir)\n    os.makedirs(demo_dir)\n    os.chdir(demo_dir)\n\n    try:\n        # 1. Initialize a Git repository\n        subprocess.run(['git', 'init', '-b', 'main'], check=True, capture_output=True)\n        subprocess.run(['git', 'config', 'user.email', 'test@example.com'], check=True, capture_output=True)\n        subprocess.run(['git', 'config', 'user.name', 'Test User'], check=True, capture_output=True)\n        \n        # 2. Create a minimal pyproject.toml for configuration\n        pyproject_content = '''\n[tool.semantic_release]\nbranch = \"main\"\nversion_source = \"tag\"\nchangelog_file = \"CHANGELOG.md\"\n'''\n        with open(\"pyproject.toml\", \"w\") as f:\n            f.write(pyproject_content)\n\n        # 3. Add some initial content and commit\n        with open('README.md', 'w') as f:\n            f.write('# My Project\\n\\nThis is a demo project.')\n        subprocess.run(['git', 'add', 'README.md', 'pyproject.toml'], check=True, capture_output=True)\n        subprocess.run(['git', 'commit', '-m', 'feat: Initial commit and project setup'], check=True, capture_output=True)\n        print(\"Successfully set up demo Git repository and pyproject.toml.\\n\")\n\n        # 4. Run semantic-release in dry-run mode\n        print(\"--- Running semantic-release publish (dry run) ---\")\n        result = subprocess.run(\n            ['semantic-release', 'publish', '--dry-run'],\n            capture_output=True,\n            text=True,\n            check=True\n        )\n        print(\"STDOUT:\\n\", result.stdout)\n        print(\"STDERR:\\n\", result.stderr)\n        print(\"\\nSemantic Release Dry Run completed successfully! Above is the simulated output.\")\n        print(\"\\nTo perform a real release, remove '--dry-run' and ensure a remote Git repository is configured.\")\n\n    except subprocess.CalledProcessError as e:\n        print(f\"Error during semantic-release demo: {e}\")\n        print(\"STDOUT:\\n\", e.stdout)\n        print(\"STDERR:\\n\", e.stderr)\n    finally:\n        os.chdir('..')\n        shutil.rmtree(demo_dir, ignore_errors=True)\n        print(f\"\\nCleaned up temporary directory: {demo_dir}\")\n\nif __name__ == '__main__':\n    run_semantic_release_demo()\n","lang":"python","description":"This quickstart demonstrates how to programmatically invoke the `semantic-release` CLI using `subprocess.run` in Python. It sets up a temporary Git repository and a minimal `pyproject.toml` to make the `semantic-release publish --dry-run` command runnable in isolation. The primary way to use `python-semantic-release` is via its `semantic-release` CLI command, typically integrated into CI/CD pipelines. Ensure your project has a properly configured `pyproject.toml` and a suitable Git history for real releases."},"warnings":[{"fix":"Migrate your project configuration to the `[tool.semantic_release]` section in `pyproject.toml`. Refer to the official documentation for the updated syntax and options.","message":"Configuration was fully moved from legacy files like `release.config.json` or `setup.cfg` to `pyproject.toml`. Older configuration files are no longer parsed.","severity":"breaking","affected_versions":"< 8.0.0 (migration to >= 8.0.0)"},{"fix":"Upgrade your Python environment to version 3.8 or a later compatible version.","message":"Python 3.7 support has been officially dropped. The library now requires Python 3.8 or newer.","severity":"breaking","affected_versions":">= 10.0.0"},{"fix":"Update your `pyproject.toml` file to use `commit_analyzer` instead of `commit_parser` under the `[tool.semantic_release]` section.","message":"The configuration option `commit_parser` was renamed to `commit_analyzer` in `pyproject.toml`.","severity":"breaking","affected_versions":">= 10.0.0"},{"fix":"Configure your CI/CD pipeline to perform a full Git clone (e.g., `fetch-depth: 0` for GitHub Actions `checkout` action) to ensure all necessary history and tags are available.","message":"Shallow Git clones in CI/CD pipelines (e.g., `fetch-depth: 1` in GitHub Actions checkout) can prevent `semantic-release` from accessing full commit history or older tags, leading to incorrect version calculations or failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that `version_source` (e.g., `tag`, `file`) is correctly set in `pyproject.toml`. If using `file`, ensure `version_variable` specifies the exact relative path to the file and the name of the variable (e.g., `src/my_package/__init__.py:__version__`).","message":"Incorrectly configured `version_source` or `version_variable` paths can cause `semantic-release` to fail finding or updating the project's version string.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}