### Example Changelog File Content Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md This is an example of the content found in a package's changelog file. ```text * Mon Nov 25 2019 Foo Bar 2.3.5-1 - Update to 2.3.5 * Wed Jul 25 2018 Foo Bar 2.3.4-1 - Fix building for armv7 with gcc10 (required for the mass rebuild) * Thu Feb 06 2020 John Doe - 1.5-2 - Fix building for armv7 with gcc10 * Thu Feb 06 2020 Foo Bar - 1.5-1 - Update to 1.5 * Sat Jul 14 2018 Jane Smith - 1.0-1 - Update to 1.0 * Mon Jun 18 2018 Jane Smith - 0.9-1 - Initial import ``` -------------------------------- ### Install and Run RPMAutospec Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Commands to install the package using uv or virtual environments and execute the CLI tool. ```bash # Install uv if not already installed pip install uv # Clone the repository git clone https://github.com/fedora-infra/rpmautospec.git cd rpmautospec # Install with all dependencies uv sync # Or install with specific optional dependencies uv sync --extra click --extra pygit2 # Run the CLI tool uv run rpmautospec --help # Alternative: Install from source in a virtualenv python -m venv venv source venv/bin/activate pip install -e ".[all]" ``` -------------------------------- ### Install rpmautospec dependencies Source: https://github.com/fedora-infra/rpmautospec/blob/main/README.rst Use uv to synchronize the project environment. ```bash uv sync ``` -------------------------------- ### Example Git Commit History Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md This illustrates a simplified Git commit history relevant to changelog generation. ```text K: Fix build on s390x | | [skip changelog] | J: Update to 2.4 | I: Fix typo in the changelog file | H: Fix typo in patch001 | G: Move changelog to ``changelog`` and fix typo | F: Update to 2.3.5 | E: Update to 2.3.4 | D: Fix building on armv7 with gcc10 | C: Update to 1.5 | B: Update to 1.0 | A: Initial import ``` -------------------------------- ### Generated Changelog Example Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md This is the resulting changelog after rpmautospec processes the commits and the existing changelog file. ```text * Mon Mar 02 2020 Jane Smith - 2.4-1 - Update to 2.4 * Mon Nov 25 2019 Foo Bar 2.3.5-1 - Update to 2.3.5 * Wed Jul 25 2018 Foo Bar 2.3.4-1 - Update to 2.3.4 * Thu Feb 06 2020 John Doe - 1.5-2 - Fix building for armv7 with gcc10 (required for the mass rebuild) * Thu Feb 06 2020 Foo Bar - 1.5-1 - Update to 1.5 * Sat Jul 14 2018 Jane Smith - 1.0-1 - Update to 1.0 * Mon Jun 18 2018 Jane Smith - 0.9-1 - Initial import ``` -------------------------------- ### Custom Base Release Usage Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Using the -b parameter to set a starting release number other than 1. ```spec Summary: test-autorelease-baserelease Name: test-autorelease-baserelease Version: 1.0 Release: %autorelease -b 100 License: MIT %description An example package for the %%autorelease macro. This package demonstrates using a base release number which lets release numbers start at other values than 1 (the default). ``` ```text test-autorelease-baserelease-1.0-100.fc34.x86_64 ``` -------------------------------- ### Git history example for changelog generation Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md Visual representation of git history used to generate a changelog when no static changelog file exists. ```text F: Update to 2.3.4 | E: Fix build on arm64 | | Fixes bug introduced in previous commit. | [skip changelog] | D: Fix building on armv7 with gcc10 | | ... (required for the mass rebuild). | C: Update to 1.5 | B: Update to 1.0 | A: Initial import ``` ```text * Wed Jul 25 2018 Foo Bar - 2.3.4-1 - Update to 2.3.4 * Thu Feb 06 2020 John Doe - 1.5-2 - Fix building for armv7 with gcc10 (required for the mass rebuild) * Thu Feb 06 2020 Foo Bar - 1.5-1 - Update to 1.5 * Sat Jul 14 2018 Jane Smith - 1.0-1 - Update to 1.0 * Mon Jun 18 2018 Jane Smith - 0.9-1 - Initial import ``` -------------------------------- ### Viewing rpmautospec header in spec files Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/peculiarities.md Example of the metadata header injected by rpmautospec at the top of preprocessed spec files. ```text ## START: Set by rpmautospec ## (rpmautospec version 0.3.0) ## RPMAUTOSPEC: autorelease, autochangelog ... ## END: Set by rpmautospec ``` -------------------------------- ### Configure %autorelease Macro Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Examples of using the %autorelease macro in an RPM spec file to automate release numbering. ```spec # Basic usage - replaces manual release like "Release: 7{%dist}" Summary: my-package Name: my-package Version: 1.0 Release: %autorelease License: MIT %description Example package using autorelease. # With custom base release (start at 100 instead of 1) Release: %autorelease -b 100 # Pre-release with extraver (e.g., 1.0-0.1.pre1.fc34) Release: %autorelease -p -e pre1 # Snapshot release (e.g., 1.0-1.20200317git1234abcd.fc34) Release: %autorelease -s 20200317git1234abcd # Combined extraver and snapshot Release: %autorelease -e pre1 -s 20200317git1234abcd # Without dist tag (for use in macros) Release: %autorelease -n ``` -------------------------------- ### Flagging unresolvable merges Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/peculiarities.md Example of the warning message inserted into the changelog when rpmautospec cannot determine changes due to a merge. ```text - RPMAUTOSPEC: unresolvable merge ``` -------------------------------- ### Clone and enter a package repository Source: https://github.com/fedora-infra/rpmautospec/blob/main/README.rst Prepare a local environment for testing rpmautospec with a specific package. ```bash fedpkg clone guake cd guake ``` -------------------------------- ### Pre-Release Case Usage Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Using -p and -e parameters to handle pre-release versioning. ```spec Summary: test-autorelease-prerelease Name: test-autorelease-prerelease Version: 1.0 Release: %autorelease -p -e pre1 License: MIT %description An example package testing the %%autorelease macro. This package is for testing a prerelease with an part, when upstream uses unsortable versions like "1.0pre1". ``` ```text test-autorelease-prerelease-1.0-0.1.pre1.fc34.x86_64 ``` -------------------------------- ### Convert packages with PkgConverter Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Automate the conversion of spec files to use %autorelease and %autochangelog macros while managing git repository state. ```python from rpmautospec.subcommands.convert import ( PkgConverter, FileModifiedError, FileUntrackedError, ) from rpmautospec.exc import SpecParseFailure # Initialize converter try: converter = PkgConverter("/path/to/package") except FileNotFoundError as e: print(f"Package not found: {e}") except FileModifiedError as e: print(f"Repository has uncommitted changes: {e}") except FileUntrackedError as e: print(f"Spec file is untracked: {e}") except FileExistsError as e: print(f"Changelog file already exists: {e}") # Load the spec file converter.load() # Convert to autorelease try: converter.convert_to_autorelease() print("Converted Release field to %autorelease") except SpecParseFailure as e: print(f"Conversion failed: {e}") # Convert to autochangelog try: converter.convert_to_autochangelog() print("Converted %changelog to %autochangelog") except SpecParseFailure as e: print(f"Conversion failed: {e}") # Save changes to disk converter.save() # Commit changes to git converter.commit( message="Convert to rpmautospec\n\n[skip changelog]", signoff=True ) # Check what was converted print(f"Converted release: {converter.converted_release}") print(f"Converted changelog: {converter.converted_changelog}") print(f"Made commit: {converter.made_commit}") print(f"Summary: {converter.describe_changes(for_git=False)}") ``` -------------------------------- ### Configure autorelease with both extra version and snapshot Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Combine both -e and -s flags to handle complex versioning scenarios involving both pre-releases and snapshots. ```spec Summary: test-autorelease-extraver-snapshot Name: test-autorelease-extraver-snapshot Version: 1.0 Release: %autorelease -e pre1 -s 20200317git1234abcd License: MIT %description An example package testing the %%autorelease macro. This package is for testing with and parts, when upstream uses unsortable versions like "1.0pre1" and we package a snapshot after it. ``` -------------------------------- ### Manual Release Bumping Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Syntax for forcing a minimum release number via a commit log comment. ```text [bump release: ] ``` -------------------------------- ### Configure autorelease with extra version Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Use the -e flag to handle upstream versions that are not easily sortable, such as pre-releases. ```spec Summary: test-autorelease-extraver Name: test-autorelease-extraver Version: 1.0 Release: %autorelease -e pre1 License: MIT %description An example package testing the %%autorelease macro. This package is for testing with an part, when upstream uses unsortable versions like "1.0pre1". ``` -------------------------------- ### rpmautospec CLI - convert Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Converts traditional RPM spec files to use rpmautospec macros. ```APIDOC ## rpmautospec convert ### Description Automatically converts traditional spec files to use rpmautospec, modifying the spec file to use `%autorelease` and `%autochangelog` macros, moving existing changelog content to a separate `changelog` file, and optionally committing the changes. ### Method CLI command ### Endpoint N/A (CLI tool) ### Parameters #### Path Parameters - **/path/to/package** (string) - Optional - Path to the specific package directory to convert. #### Query Parameters - **--no-commit** - Optional - Convert without committing the changes. - **-m "message"** - Optional - Use a custom commit message. - **--no-changelog** - Optional - Convert only the release field, keeping the manual changelog. - **--no-release** - Optional - Convert only the changelog, keeping the manual release. - **--signoff** - Optional - Add a Signed-off-by line to the commit. #### Request Body None ### Request Example ```bash # Convert package in current directory (commits changes by default) rpmautospec convert # Convert specific package directory rpmautospec convert /path/to/package # Convert without committing rpmautospec convert --no-commit # Convert with custom commit message rpmautospec convert -m "Switch to rpmautospec for release and changelog management" # Convert only the release field (keep manual changelog) rpmautospec convert --no-changelog # Convert only the changelog (keep manual release) rpmautospec convert --no-release # Add Signed-off-by line to commit rpmautospec convert --signoff ``` ### Response N/A (CLI output and file modification) #### Success Response (0) Spec file is converted and changes are committed (if not disabled). #### Response Example (Output depends on the package and git history) ``` -------------------------------- ### Python API - PkgHistoryProcessor Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Low-level API for processing package git history with custom visitors. Provides fine-grained control over history processing using a visitor pattern. ```APIDOC ## Python API - PkgHistoryProcessor Low-level API for processing package git history with custom visitors. The `PkgHistoryProcessor` class provides fine-grained control over history processing. It uses a visitor pattern to traverse git commits and extract information like release numbers and changelog entries. This is useful for custom tooling and advanced integrations. ```python from pathlib import Path from rpmautospec.pkg_history import PkgHistoryProcessor from rpmautospec.specparser import SpecParserError # Initialize processor for a package try: processor = PkgHistoryProcessor("/path/to/package") except FileNotFoundError as e: print(f"Package not found: {e}") except SpecParserError as e: print(f"Spec parse error: {e}") # Run with release number visitor only result = processor.run(visitors=(processor.release_number_visitor,)) print(f"Release number: {result['release-number']}") print(f"Complete release: {result['release-complete']}") print(f"Epoch-Version: {result['epoch-version']}") print(f"Version flags: {result['verflags']}") # Run with both release and changelog visitors result = processor.run(visitors=( processor.release_number_visitor, processor.changelog_visitor, )) for entry in result['changelog']: print(entry.format()) # Get all results for all commits (useful for analysis) all_results = processor.run( visitors=(processor.release_number_visitor,), all_results=True ) for commit, data in all_results.items(): print(f"{commit.short_id}: release {data['release-number']}") # Process from a specific commit result = processor.run( head="abc1234", # commit hash visitors=(processor.release_number_visitor,) ) ``` ``` -------------------------------- ### Generate RPM changelog Source: https://github.com/fedora-infra/rpmautospec/blob/main/README.rst Create a changelog based on repository contents and commit history. ```bash rpmautospec generate-changelog ``` -------------------------------- ### Convert Existing Package Changelog Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/opting-in.md Use the 'rpmautospec convert' command to migrate existing changelog entries from your spec file to a separate 'changelog' file for use with %autochangelog. This conversion should be done in a single commit. ```console $ rpmautospec convert ``` -------------------------------- ### Configure autorelease with snapshot information Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Use the -s flag to include snapshot metadata for packages built from specific git commits. ```spec Summary: test-autorelease-snapshot Name: test-autorelease-snapshot Version: 1.0 Release: %autorelease -s 20200317git1234abcd License: MIT %description An example package testing the %%autorelease macro. This package is for testing with a part, for a snapshot between versions from an upstream repository. ``` -------------------------------- ### Preprocess spec files for builds Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Invokes the distgit processing logic for packages that require automatic release or changelog generation. ```python if features.has_autorelease or features.has_autochangelog: # Preprocess the spec file from rpmautospec import process_distgit process_distgit(spec_path.parent) ``` -------------------------------- ### Simple %autorelease Usage Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Standard implementation of the %autorelease macro in a spec file. ```spec Summary: test-autorelease Name: test-autorelease Version: 1.0 Release: %autorelease License: MIT %description An example package testing the %%autorelease macro. This package is for testing the normal release cadence, bumping in the left-most, most significant place of the release field. ``` ```text test-autorelease-1.0-1.fc34.x86_64 ``` -------------------------------- ### RPMAutospec CLI Commands Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Common CLI operations for generating changelogs, calculating releases, and processing spec files. ```bash # Show help and available commands rpmautospec --help # Generate changelog from git history rpmautospec generate-changelog /path/to/package rpmautospec generate-changelog . # Current directory # Calculate release number rpmautospec calculate-release /path/to/package # Output: Calculated release number: 5 # Calculate only the numeric release (without flags) rpmautospec calculate-release --number-only /path/to/package # Output: Calculated release number: 5 # Process a spec file for building (used by Koji plugin) rpmautospec process-distgit /path/to/package.spec /path/to/output.spec # Increase verbosity or enable debugging rpmautospec --debug generate-changelog . rpmautospec --quiet calculate-release . # Disable pager for changelog output rpmautospec --no-pager generate-changelog . ``` -------------------------------- ### Performing an empty rebuild Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/peculiarities.md Command to create a commit without changes, necessary for triggering a rebuild in rpmautospec. ```bash git commit --allow-empty -m 'Rebuild for …' ``` -------------------------------- ### Convert Package to rpmautospec Source: https://context7.com/fedora-infra/rpmautospec/llms.txt The `convert` command modifies spec files to use rpmautospec macros, moves changelog content, and optionally commits changes. Use `--no-commit` to prevent automatic commits. ```bash rpmautospec convert ``` ```bash rpmautospec convert /path/to/package ``` ```bash rpmautospec convert --no-commit ``` ```bash rpmautospec convert -m "Switch to rpmautospec for release and changelog management" ``` ```bash rpmautospec convert --no-changelog ``` ```bash rpmautospec convert --no-release ``` ```bash rpmautospec convert --signoff ``` ```bash cd /path/to/my-package git status # Ensure clean working tree rpmautospec convert git log -1 # Verify the conversion commit git push origin main ``` -------------------------------- ### Release Field Structure Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md The standard structure of the release field in Fedora packaging. ```spec %{?dist}[.] ``` -------------------------------- ### Python API - PkgConverter Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Programmatically convert packages to use rpmautospec. Handles spec file modification, changelog file creation, and git operations while ensuring repository integrity. ```APIDOC ## Python API - PkgConverter Programmatically convert packages to use rpmautospec. The `PkgConverter` class provides programmatic access to the conversion functionality. It handles spec file modification, changelog file creation, and git operations while ensuring repository integrity. ```python from rpmautospec.subcommands.convert import ( PkgConverter, FileModifiedError, FileUntrackedError, ) from rpmautospec.exc import SpecParseFailure # Initialize converter try: converter = PkgConverter("/path/to/package") except FileNotFoundError as e: print(f"Package not found: {e}") except FileModifiedError as e: print(f"Repository has uncommitted changes: {e}") except FileUntrackedError as e: print(f"Spec file is untracked: {e}") except FileExistsError as e: print(f"Changelog file already exists: {e}") # Load the spec file converter.load() # Convert to autorelease try: converter.convert_to_autorelease() print("Converted Release field to %autorelease") except SpecParseFailure as e: print(f"Conversion failed: {e}") # Convert to autochangelog try: converter.convert_to_autochangelog() print("Converted %changelog to %autochangelog") except SpecParseFailure as e: print(f"Conversion failed: {e}") # Save changes to disk converter.save() # Commit changes to git converter.commit( message="Convert to rpmautospec\n\n[skip changelog]", signoff=True ) # Check what was converted print(f"Converted release: {converter.converted_release}") print(f"Converted changelog: {converter.converted_changelog}") print(f"Made commit: {converter.made_commit}") print(f"Summary: {converter.describe_changes(for_git=False)}") ``` ``` -------------------------------- ### Verify release field Source: https://github.com/fedora-infra/rpmautospec/blob/main/tests/test-data/repodata/README.md Extracts the release field from a spec file for verification. ```bash rpm --specfile --qf '%{release}\n' ``` -------------------------------- ### Calculate Complete Release with Python API Source: https://context7.com/fedora-infra/rpmautospec/llms.txt The `calculate_release` function analyzes git history to return the complete release string, including pre-release markers. Use `error_on_unparseable_spec=False` to handle unparseable specs gracefully. ```python from rpmautospec import calculate_release, calculate_release_number from rpmautospec.exc import SpecParseFailure # Calculate complete release (e.g., "0.5.pre1" for pre-release) try: release = calculate_release("/path/to/package") print(f"Complete release: {release}") # Output: Complete release: 5 except SpecParseFailure as e: print(f"Failed to parse spec: {e}") ``` ```python # Calculate only the release number release_num = calculate_release_number("/path/to/package") print(f"Release number: {release_num}") # Output: Release number: 5 ``` ```python # Pass spec file directly release = calculate_release("/path/to/package/mypackage.spec") ``` ```python # Handle unparseable specs gracefully release = calculate_release( "/path/to/package", error_on_unparseable_spec=False ) ``` -------------------------------- ### Python API - process_distgit Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Processes a spec file for building, injecting release macros and changelog. ```APIDOC ## Python API - process_distgit ### Description The core preprocessing function used by the Koji plugin. Analyzes the repository, computes the release number, generates the changelog, and writes a processed spec file with all values frozen for reproducible builds. ### Method Python function call ### Endpoint N/A (Python API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Function Signature `process_distgit(path: str, target: Optional[str] = None, enable_caching: bool = True, error_on_unparseable_spec: bool = True) -> bool` ### Parameters - **path** (string) - Required - Path to the package repository. - **target** (string) - Optional - Path to write the processed spec file. If None, modifies the spec file in place. - **enable_caching** (boolean) - Optional - Whether to enable caching for the process. Defaults to True. - **error_on_unparseable_spec** (boolean) - Optional - If True, raises `SpecParseFailure` for unparseable specs. If False, handles gracefully. ### Request Example ```python from rpmautospec import process_distgit from rpmautospec.exc import SpecParseFailure # Process spec file in place try: was_processed = process_distgit("/path/to/package") if was_processed: print("Spec file was processed with rpmautospec features") else: print("Spec file doesn't use rpmautospec features") except SpecParseFailure as e: print(f"Failed to process: {e}") # Process to a different target file process_distgit( "/path/to/package", target="/path/to/output/package.spec" ) # Disable caching (for long-running processes) process_distgit( "/path/to/package", enable_caching=False ) # The processed spec file will have a header like: # ## START: Set by rpmautospec # ## (rpmautospec version 0.8.4) # ## RPMAUTOSPEC: autorelease, autochangelog # %define autorelease(e:s:pb:n) %{?-p:0.}%{lua: # release_number = 5; # ... # } # ## END: Set by rpmautospec ``` ### Response #### Success Response - **was_processed** (boolean) - True if the spec file was processed and modified, False otherwise. #### Response Example ``` Spec file was processed with rpmautospec features ``` ``` -------------------------------- ### Verify changelog block Source: https://github.com/fedora-infra/rpmautospec/blob/main/tests/test-data/repodata/README.md Extracts the changelog block from a spec file for verification. ```bash rpm --specfile --changelog ``` -------------------------------- ### Extended commit message for changelog Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md Use an ellipsis to append text to the first entry and dashed lines for additional list items. ```text Update to version 2.3.5 ... (rhbz#667, rhbz#123, and a few other nasty bugs) - Fixes build issues on s390 (rhbz#668) (Text without a dash is ignored.) ``` ```text * Mon Nov 26 2019 Foo Bar 2.3.5-1 - Update to version 2.3.5 (rhbz#667, rhbz#123, and a few other nasty bugs) - Fixes build issues on s390 (rhbz#668) ``` -------------------------------- ### Python API - do_generate_changelog Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Generates changelog content programmatically from git history. ```APIDOC ## Python API - do_generate_changelog ### Description Generates a formatted changelog string from the package's git history and optional `changelog` file. Each entry includes the commit date, author, version-release, and formatted commit message. ### Method Python function call ### Endpoint N/A (Python API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Function Signature `do_generate_changelog(path: str, error_on_unparseable_spec: bool = True) -> str` ### Parameters - **path** (string) - Required - Path to the package repository or spec file. - **error_on_unparseable_spec** (boolean) - Optional - If True, raises `SpecParseFailure` for unparseable specs. If False, handles gracefully. ### Request Example ```python from rpmautospec.subcommands.changelog import do_generate_changelog from rpmautospec.exc import SpecParseFailure # Generate changelog for a package try: changelog = do_generate_changelog("/path/to/package") print(changelog) # Output: # * Wed Jul 25 2018 Foo Bar - 2.3.4-1 # - Update to 2.3.4 # # * Thu Feb 06 2020 John Doe - 1.5-2 # - Fix building for armv7 with gcc10 # # * Thu Feb 06 2020 Foo Bar - 1.5-1 # - Update to 1.5 except SpecParseFailure as e: print(f"Error: {e}") # Handle unparseable specs changelog = do_generate_changelog( "/path/to/package", error_on_unparseable_spec=False ) # Generate from spec file directly changelog = do_generate_changelog("/path/to/package/mypackage.spec") ``` ### Response #### Success Response - **changelog** (string) - The generated changelog content. #### Response Example ``` * Wed Jul 25 2018 Foo Bar - 2.3.4-1 - Update to 2.3.4 * Thu Feb 06 2020 John Doe - 1.5-2 - Fix building for armv7 with gcc10 ``` ``` -------------------------------- ### Python API - calculate_release Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Calculates the release number programmatically using the Python API. ```APIDOC ## Python API - calculate_release ### Description Analyzes the git history of a package repository and returns either the complete release string (with flags like pre-release markers) or just the numeric release number. Useful for build systems and automation scripts. ### Method Python function call ### Endpoint N/A (Python API) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Function Signature `calculate_release(path: str, error_on_unparseable_spec: bool = True) -> str` `calculate_release_number(path: str, error_on_unparseable_spec: bool = True) -> int` ### Parameters - **path** (string) - Required - Path to the package repository or spec file. - **error_on_unparseable_spec** (boolean) - Optional - If True, raises `SpecParseFailure` for unparseable specs. If False, returns a default value or handles gracefully. ### Request Example ```python from rpmautospec import calculate_release, calculate_release_number from rpmautospec.exc import SpecParseFailure # Calculate complete release (e.g., "0.5.pre1" for pre-release) try: release = calculate_release("/path/to/package") print(f"Complete release: {release}") # Output: Complete release: 5 except SpecParseFailure as e: print(f"Failed to parse spec: {e}") # Calculate only the release number release_num = calculate_release_number("/path/to/package") print(f"Release number: {release_num}") # Output: Release number: 5 # Pass spec file directly release = calculate_release("/path/to/package/mypackage.spec") # Handle unparseable specs gracefully release = calculate_release( "/path/to/package", error_on_unparseable_spec=False ) ``` ### Response #### Success Response - **release** (string) - The calculated release string or number. #### Response Example ``` Complete release: 5 Release number: 5 ``` ``` -------------------------------- ### Traditional Versioning Release Structure Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autorelease.md Extended release field structure for legacy versioning requirements. ```spec [.][.]%{?dist}[.] ``` -------------------------------- ### Add %autochangelog for New Packages Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/opting-in.md For new packages without git history, add '%changelog' followed by '%autochangelog' at the end of your spec file to automatically generate changelogs from git commit history. ```spec %changelog %autochangelog ``` -------------------------------- ### Process package git history with PkgHistoryProcessor Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Use PkgHistoryProcessor to traverse git commits and extract release numbers or changelog entries using visitor patterns. ```python from pathlib import Path from rpmautospec.pkg_history import PkgHistoryProcessor from rpmautospec.specparser import SpecParserError # Initialize processor for a package try: processor = PkgHistoryProcessor("/path/to/package") except FileNotFoundError as e: print(f"Package not found: {e}") except SpecParserError as e: print(f"Spec parse error: {e}") # Run with release number visitor only result = processor.run(visitors=(processor.release_number_visitor,)) print(f"Release number: {result['release-number']}") print(f"Complete release: {result['release-complete']}") print(f"Epoch-Version: {result['epoch-version']}") print(f"Version flags: {result['verflags']}") # Run with both release and changelog visitors result = processor.run(visitors=( processor.release_number_visitor, processor.changelog_visitor, )) for entry in result['changelog']: print(entry.format()) # Get all results for all commits (useful for analysis) all_results = processor.run( visitors=(processor.release_number_visitor,), all_results=True ) for commit, data in all_results.items(): print(f"{commit.short_id}: release {data['release-number']}") # Process from a specific commit result = processor.run( head="abc1234", # commit hash visitors=(processor.release_number_visitor,) ) ``` -------------------------------- ### Simple commit message for changelog Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md The first line of a commit message becomes the changelog entry, with authorship and date added automatically. ```text Update to version 2.3.4 (rhbz#666) This also fixes build issues on arm64. ``` ```text * Mon Nov 25 2019 Foo Bar 2.3.4-1 - Update to version 2.3.4 (rhbz#666) ``` -------------------------------- ### Control behavior with magic comments Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Use specific annotations in git commit messages to skip changelog entries or force release bumps. ```bash # Skip changelog entry for this commit git commit -m "Fix typo in previous commit [skip changelog]" # Bump release to a minimum value (useful for package splits) # If the subpackage was previously at release 4, continue from 5 git commit -m "Split foo subpackage into separate component [bump release: 5]" # Both can be combined git commit -m "Infrastructure changes for package split [skip changelog] [bump release: 10]" # Create an empty commit for rebuilds git commit --allow-empty -m "Rebuild for Python 3.12" # The magic comments can appear anywhere in the commit body git commit -m "Update to version 2.0 This is a major update with breaking changes. See upstream release notes for details. [skip changelog]" ``` -------------------------------- ### rpmautospec CLI - generate-changelog Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Generates changelog entries from unparseable spec files. ```APIDOC ## rpmautospec generate-changelog ### Description Handles unparseable spec files gracefully by generating a changelog. ### Method CLI command ### Endpoint N/A (CLI tool) ### Parameters #### Path Parameters - **.** (string) - Required - Path to the package directory. #### Query Parameters None #### Request Body None ### Request Example ```bash rpmautospec --no-error-on-unparseable-spec generate-changelog . ``` ### Response N/A (CLI output) #### Success Response (0) Output of the generated changelog. #### Response Example (Output depends on the spec file and git history) ``` -------------------------------- ### Generate Changelog with rpmautospec CLI Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Use the `generate-changelog` command to create a changelog from spec files. The `--no-error-on-unparseable-spec` flag allows processing even if the spec file has issues. ```bash rpmautospec --no-error-on-unparseable-spec generate-changelog . ``` -------------------------------- ### Process Spec File for Distgit with Python API Source: https://context7.com/fedora-infra/rpmautospec/llms.txt The `process_distgit` function preprocesses spec files for building, injecting release macros and changelog. It can process in-place or to a target file, and caching can be disabled. ```python from rpmautospec import process_distgit from rpmautospec.exc import SpecParseFailure # Process spec file in place try: was_processed = process_distgit("/path/to/package") if was_processed: print("Spec file was processed with rpmautospec features") else: print("Spec file doesn't use rpmautospec features") except SpecParseFailure as e: print(f"Failed to process: {e}") ``` ```python # Process to a different target file process_distgit( "/path/to/package", target="/path/to/output/package.spec" ) ``` ```python # Disable caching (for long-running processes) process_distgit( "/path/to/package", enable_caching=False ) ``` ```text # The processed spec file will have a header like: # ## START: Set by rpmautospec # ## (rpmautospec version 0.8.4) # ## RPMAUTOSPEC: autorelease, autochangelog # %define autorelease(e:s:pb:n) %{?-p:0.}%{lua: # release_number = 5; # ... # } # ## END: Set by rpmautospec ``` -------------------------------- ### Configure %autochangelog Macro Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Usage of the %autochangelog macro to generate changelog entries from git commit history. ```spec # In your spec file, replace the changelog section: %changelog %autochangelog # Git commits automatically become changelog entries. # Commit message format: # # Update to version 2.3.4 (rhbz#666) # # Becomes: # * Mon Nov 25 2019 Foo Bar - 2.3.4-1 # - Update to version 2.3.4 (rhbz#666) # Multi-line changelog entries using ellipsis continuation: # # Update to version 2.3.5 # # ... (rhbz#667, rhbz#123, and a few other nasty bugs) # - Fixes build issues on s390 (rhbz#668) # # Becomes: # * Mon Nov 26 2019 Foo Bar - 2.3.5-1 # - Update to version 2.3.5 (rhbz#667, rhbz#123, and a few other nasty bugs) # - Fixes build issues on s390 (rhbz#668) # Skip changelog entry for a commit by adding this line: # [skip changelog] ``` -------------------------------- ### Replace Manual Release with %autorelease Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/opting-in.md Replace the manually set 'Release' field in your spec file with the %autorelease macro for automated release management. Consider switching before a version bump to avoid initial release number jumps. ```spec Release: 7{%dist} ``` ```spec Release: %autorelease ``` -------------------------------- ### Skip changelog entry Source: https://github.com/fedora-infra/rpmautospec/blob/main/doc/autochangelog.md Include [skip changelog] on a separate line in the commit message to omit it from the generated changelog. ```text [skip changelog] ``` -------------------------------- ### Generate Changelog Content with Python API Source: https://context7.com/fedora-infra/rpmautospec/llms.txt The `do_generate_changelog` function creates a formatted changelog string from git history. It can handle unparseable specs if `error_on_unparseable_spec` is set to `False`. ```python from rpmautospec.subcommands.changelog import do_generate_changelog from rpmautospec.exc import SpecParseFailure # Generate changelog for a package try: changelog = do_generate_changelog("/path/to/package") print(changelog) # Output: # * Wed Jul 25 2018 Foo Bar - 2.3.4-1 # - Update to 2.3.4 # # * Thu Feb 06 2020 John Doe - 1.5-2 # - Fix building for armv7 with gcc10 # # * Thu Feb 06 2020 Foo Bar - 1.5-1 # - Update to 1.5 except SpecParseFailure as e: print(f"Error: {e}") ``` ```python # Handle unparseable specs changelog = do_generate_changelog( "/path/to/package", error_on_unparseable_spec=False ) ``` ```python # Generate from spec file directly changelog = do_generate_changelog("/path/to/package/mypackage.spec") ``` -------------------------------- ### Calculate RPM release field Source: https://github.com/fedora-infra/rpmautospec/blob/main/README.rst Determine the release number based on commits since the last version update. ```bash rpmautospec calculate-release ``` -------------------------------- ### Inspect spec file features Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Retrieves detailed information about the presence of autorelease and autochangelog macros in a spec file. ```python features = check_specfile_features(spec_path) print(f"Has %autorelease: {features.has_autorelease}") print(f"Has %autochangelog: {features.has_autochangelog}") print(f"Already processed: {features.is_processed}") print(f"Changelog line number: {features.changelog_lineno}") print(f"Autochangelog line number: {features.autochangelog_lineno}") ``` -------------------------------- ### Check spec file for rpmautospec usage Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Verify if a spec file utilizes rpmautospec features using the core library functions. ```python from rpmautospec import specfile_uses_rpmautospec from rpmautospec_core import check_specfile_features from pathlib import Path ``` -------------------------------- ### Detect rpmautospec usage Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Checks if a given spec file utilizes rpmautospec macros. ```python spec_path = Path("/path/to/package/mypackage.spec") if specfile_uses_rpmautospec(spec_path): print("Spec file uses rpmautospec") else: print("Spec file uses traditional release/changelog") ``` -------------------------------- ### Checking rpmautospec Usage Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Detect whether a spec file uses rpmautospec features. The `specfile_uses_rpmautospec` function checks if a spec file uses any rpmautospec macros. ```APIDOC ## Checking rpmautospec Usage Detect whether a spec file uses rpmautospec features. The `specfile_uses_rpmautospec` function (imported from rpmautospec-core) checks if a spec file uses any rpmautospec macros. This is useful for build systems to determine if preprocessing is needed. ```python from rpmautospec import specfile_uses_rpmautospec from rpmautospec_core import check_specfile_features from pathlib import Path ``` ``` -------------------------------- ### Magic Comments in Commit Messages Source: https://context7.com/fedora-infra/rpmautospec/llms.txt Control changelog generation and release bumping through special commit message annotations. These comments are parsed from commit messages and affect how rpmautospec processes the repository history. ```APIDOC ## Magic Comments in Commit Messages Control changelog generation and release bumping through special commit message annotations. Magic comments allow packagers to skip changelog entries for trivial commits or bump release numbers for special cases like package splits. These comments are parsed from commit messages and affect how rpmautospec processes the repository history. ```bash # Skip changelog entry for this commit git commit -m "Fix typo in previous commit [skip changelog]" # Bump release to a minimum value (useful for package splits) # If the subpackage was previously at release 4, continue from 5 git commit -m "Split foo subpackage into separate component [bump release: 5]" # Both can be combined git commit -m "Infrastructure changes for package split [skip changelog] [bump release: 10]" # Create an empty commit for rebuilds git commit --allow-empty -m "Rebuild for Python 3.12" # The magic comments can appear anywhere in the commit body git commit -m "Update to version 2.0 This is a major update with breaking changes. See upstream release notes for details. [skip changelog]" ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.