README

RU

This tool automates the process of version management in Composer-based projects by analyzing Git commits and generating a CHANGELOG. It adheres to semantic versioning and supports the Conventional Commits standard.

The version follows the semantic rule <Major>.<Minor>.<Patch>:

• Major: Breaking changes that affect backward compatibility.
• Minor: New features added without breaking existing functionality.
• Patch: Bug fixes or minor improvements.

Key Features

• Version Management: Automatically determines the next version based on commit analysis and updates composer.json.
• Git Integration: Creates Git tags for releases and handles commits according to the project's versioning strategy.
• Customizable Commit Types: Define custom commit types and their impact on version increments (major, minor, patch).
• Advanced CHANGELOG Generation:
  • Supports custom formatting for the CHANGELOG.md file.
  • Option to hide duplicate entries within the same section for cleaner output.
  • Configurable scope preservation for specific commit types.
• Support for Squashed Commits: Handles squashed commits (e.g., from git merge --squash) by parsing detailed descriptions.
• Configurable Rules: Implement custom rules for categorizing commits into sections.
• Flexible Configuration:
  • Customize the main branch name (e.g., main instead of master).
  • Configure release-related settings, such as release scope and section.
  • Ignore untracked files during version updates.
• Semantic Versioning Compliance: Ensures strict adherence to semantic versioning principles.
• Optional Composer Versioning: Disable version updates in composer.json if versioning is managed solely through Git tags.
• Extensibility:
  • Use custom parsers, formatters, and VCS executors for advanced workflows.
  • Extend functionality with custom properties via the Config class.

Why Use This Tool?

• Simplifies version management by automating repetitive tasks.
• Improves consistency in versioning and changelog generation.
• Provides flexibility for custom workflows and project-specific requirements.
• Reduces human error by relying on automated analysis of commit messages.

Installation

composer require --dev voral/version-increment

Usage

# Automatic detection of release type
./vendor/bin/vs-version-increment

# Incrementing the major version
./vendor/bin/vs-version-increment major

# Incrementing the minor version
./vendor/bin/vs-version-increment minor

# Incrementing the patch version
./vendor/bin/vs-version-increment patch

Utility help command

./vendor/bin/vs-version-increment --help

Retrieving the list of registered commit types and registered scopes

./vendor/bin/vs-version-increment --list

Execute all file updates (e.g., CHANGELOG.md, composer.json) but skip creating the final Git commit and version tag

./vendor/bin/vs-version-increment --no-commit

The --debug flag allows you to preview the changes that will be made to the CHANGELOG and version without actually applying them

# Automatic detection of release type
./vendor/bin/vs-version-increment --debug

# Incrementing the major version
./vendor/bin/vs-version-increment --debug major

# Incrementing the minor version
./vendor/bin/vs-version-increment --debug minor

# Incrementing the patch version
./vendor/bin/vs-version-increment --debug patch

To simplify usage, you can add scripts to composer.json:

{
  "scripts": {
    "vi:major": "php ./vendor/bin/vs-version-increment major",
    "vi:minor": "php ./vendor/bin/vs-version-increment minor",
    "vi:patch": "php ./vendor/bin/vs-version-increment patch",
    "vi:auto": "php ./vendor/bin/vs-version-increment",
    "vi:list": "php ./vendor/bin/vs-version-increment --list",
    "vi:debug:auto": "php ./vendor/bin/vs-version-increment --debug"
  },
  "scripts-descriptions": {
    "vi:major": "Increment major version and update CHANGELOG.md",
    "vi:minor": "Increment minor version and update CHANGELOG.md",
    "vi:patch": "Increment patch version and update CHANGELOG.md",
    "vi:auto": "Auto-detect version increment based on commit analysis",
    "vi:list": "Display registered commit types and scopes",
    "vi:debug:auto": "Preview auto-detected changes without applying them"
  }  
}

Example of the output file:

# 1.0.1 (2023-10-01)

### Features

- New endpoint user authentication
- Added support dark mode

### Fixes

- Fixed a bug with login form validation
- Resolved issue with incorrect API response

### Other

- Updated dependencies

Configuration

You can configure the script by placing a .vs-version-increment.php file in the project directory and making the following adjustments:

• Setting a Custom List of Change Types
• Configuring Change Types
• Configuring the Release Commit Type
• Configuring the Main Repository Branch
• Configuring Types for Major Version Updates
• Configuring Types for Minor Version Updates
• Release Scope Configuration
• Custom Type Distribution Rules Setup
• Ignoring Untracked Files
• Configuring CHANGELOG Formatting
  • Using a Scope-Preserving Formatter
  • Configuring Human-Readable Titles for Scopes
  • Creating a Custom Formatter
• Configuring Squashed Commits
  • Default Squashed Commit
  • Defining Squashed Commits via a Group
  • Combined Definition of a Squashed Commit
  • General Rules for Full Commit Descriptions
• Configuring the Commit Description Parser
• Disabling Version Updates in composer.json
• Sets a custom property in the configuration
• Suppress Duplicate Lines in CHANGELOG

Commit Descriptions

For the tool to function correctly, commit descriptions must follow this format:

<type>[(scope)][!]: <description>

[body]

• type: The commit type. It is recommended to use a predefined list for the project. Changes are grouped in the changelog by type. Unregistered types fall under the default category. The type configured as related to new functionality (default: feat) affects the minor version during automatic detection.
• scope (optional): The project area to which the commit applies.
• !: Indicates that the commit breaks backward compatibility. During automatic detection, this triggers a major version update.
• description: A short description.
• body: Detailed description (not used by the tool).

Examples:

feat(router): New endpoint

doc: Described all features

feat!: Removed old API endpoints

Default Commit Types

CI/CD Integration

The script can be integrated into CI/CD pipelines. In case of errors, it returns different exit codes:

You can use it in the command line, for example:

./vendor/bin/vs-version-increment && echo 'Ok' || echo 'Error'

Example for GitHub Actions:

jobs:
  version-update:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Run version increment script
        run: ./vendor/bin/vs-version-increment

Event Handling with EventBus

The module includes an EventBus for handling events that occur during the utility's operation. This allows developers to create custom event handlers and extend the tool's functionality.

Key Features:

• Event Subscription: Developers can subscribe to various events, such as the start of a version update, successful completion, or error occurrence.
• Custom Event Handlers: You can implement custom event handlers to perform additional actions, such as logging or sending notifications. The handler must implement the \Vasoft\VersionIncrement\Contract\EventListenerInterface interface.

Example Usage:

use Vasoft\VersionIncrement\Events\EventType;
use Vasoft\VersionIncrement\Config;
use Vasoft\VersionIncrement\Contract\EventListenerInterface;
use Vasoft\VersionIncrement\SemanticVersionUpdater;

class Listener implements EventListenerInterface {
    public function handle(\Vasoft\VersionIncrement\Events\Event $event): void
    {
        print_r([
            $event->getData(SemanticVersionUpdater::LAST_VERSION_TAG) ?? 'unknown',   
            $event->eventType->name,        
        ]);
    }
}
$listener = new Listener();

$config = new Config();

$eventBus = $config->getEventBus();
$eventBus->addListener(EventType::BEFORE_VERSION_SET, $listener);
$eventBus->addListener(EventType::AFTER_VERSION_SET, $listener);
$eventBus->addListener(EventType::ON_ERROR, $listener);

Available Event Types:

Recommendations:

• Use EventBus to integrate third-party systems, such as monitoring or notification systems.
• Ensure that your event handlers do not slow down the main execution process of the utility.

Error Handling for Custom Extensions

When developing custom extensions or integrations for this tool, it is important to handle errors consistently and avoid conflicts with system-defined error codes. To achieve this, developers should use the UserException class for all custom error scenarios.

Key Points:

• Reserved Error Codes: The UserException class ensures that all user-defined error codes are offset by 5000. This guarantees that custom error codes do not overlap with system-defined codes (below 5000).
• Usage Example:

  use Vasoft\VersionIncrement\Exceptions\UserException;
  
  throw new UserException(
      code: 100, // Your custom error code (will be converted to 5100)
      message: 'Custom error message describing the issue.'
  );

• Best Practices:
  • Use descriptive error messages to help users understand the cause of the error.
  • Document the meaning of custom error codes in your extension's documentation.
  • Avoid using error codes below 5000, as these are reserved for system-defined errors.

By adhering to these guidelines, you can ensure seamless integration of your custom extensions with the tool while maintaining clarity and consistency in error handling.

Configuration Examples

To help you get started with the library more quickly, I provide ready-to-use configuration examples for various use cases.

1. Configuration for Keep a Changelog

This configuration example is designed for projects that follow the Keep a Changelog standard. It organizes changes into categories (Added, Changed, Deprecated, Removed, Fixed, Security), making the changelog easy to read.

File: examples/keepachangelog.php

Useful Links

• Conventional Commits
• Semantic Versioning
• Project Repository