{"id":26797416,"url":"https://github.com/voral/vs-version-incrementor","last_synced_at":"2025-09-03T06:42:01.896Z","repository":{"id":283283189,"uuid":"951245649","full_name":"Voral/vs-version-incrementor","owner":"Voral","description":"A tool for semantic versioning and changelog generation in Composer projects based on Git commits.","archived":false,"fork":false,"pushed_at":"2025-05-15T21:15:58.000Z","size":211,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-17T01:39:50.989Z","etag":null,"topics":["changelog","changelog-generator","composer","conventional-changelog","conventional-commits","git","php","semantic-versioning","semver","version-increment"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Voral.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-19T11:36:04.000Z","updated_at":"2025-05-15T21:16:02.000Z","dependencies_parsed_at":"2025-04-15T05:24:06.451Z","dependency_job_id":"a8b0bd22-8c7e-4421-b9a3-114a3ad09e28","html_url":"https://github.com/Voral/vs-version-incrementor","commit_stats":null,"previous_names":["voral/vs-version-incrementor"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Voral/vs-version-incrementor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voral%2Fvs-version-incrementor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voral%2Fvs-version-incrementor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voral%2Fvs-version-incrementor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voral%2Fvs-version-incrementor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voral","download_url":"https://codeload.github.com/Voral/vs-version-incrementor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voral%2Fvs-version-incrementor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273403944,"owners_count":25099299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["changelog","changelog-generator","composer","conventional-changelog","conventional-commits","git","php","semantic-versioning","semver","version-increment"],"created_at":"2025-03-29T19:14:35.286Z","updated_at":"2025-09-03T06:42:01.872Z","avatar_url":"https://github.com/Voral.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Semantic Version Update\n\n[RU](https://github.com/Voral/vs-version-incrementor/blob/master/README.ru.md)\n\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/?branch=master)\n[![Code Coverage](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/?branch=master)\n[![Code Intelligence Status](https://scrutinizer-ci.com/g/Voral/vs-version-incrementor/badges/code-intelligence.svg?b=master)](https://scrutinizer-ci.com/code-intelligence) \\\n![PHP Tests](https://github.com/Voral/vs-version-incrementor/actions/workflows/php.yml/badge.svg)\n\nThis tool automates the process of version management in Composer-based projects by analyzing Git commits and generating\na `CHANGELOG`. It adheres to [semantic versioning](https://semver.org/) and supports\nthe [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.\n\nThe version follows the semantic rule `\u003cMajor\u003e.\u003cMinor\u003e.\u003cPatch\u003e`:\n\n- *Major*: Breaking changes that affect backward compatibility.\n- *Minor*: New features added without breaking existing functionality.\n- *Patch*: Bug fixes or minor improvements.\n\n## Key Features\n\n- **Version Management**: Automatically determines the next version based on commit analysis and\n  updates `composer.json`.\n- **Git Integration**: Creates Git tags for releases and handles commits according to the project's versioning strategy.\n- **Customizable Commit Types**: Define custom commit types and their impact on version\n  increments (`major`, `minor`, `patch`).\n- **Advanced CHANGELOG Generation**:\n    - Supports custom formatting for the `CHANGELOG.md` file.\n    - Option to hide duplicate entries within the same section for cleaner output.\n    - Configurable scope preservation for specific commit types.\n- **Support for Squashed Commits**: Handles squashed commits (e.g., from `git merge --squash`) by parsing detailed\n  descriptions.\n- **Configurable Rules**: Implement custom rules for categorizing commits into sections.\n- **Flexible Configuration**:\n    - Customize the main branch name (e.g., `main` instead of `master`).\n    - Configure release-related settings, such as release scope and section.\n    - Ignore untracked files during version updates.\n- **Semantic Versioning Compliance**: Ensures strict adherence to semantic versioning principles.\n- **Optional Composer Versioning**: Disable version updates in `composer.json` if versioning is managed solely through\n  Git tags.\n- **Extensibility**:\n    - Use custom parsers, formatters, and VCS executors for advanced workflows.\n    - Extend functionality with custom properties via the `Config` class.\n\n### Why Use This Tool?\n\n- Simplifies version management by automating repetitive tasks.\n- Improves consistency in versioning and changelog generation.\n- Provides flexibility for custom workflows and project-specific requirements.\n- Reduces human error by relying on automated analysis of commit messages.\n\n## Installation\n\n```bash\ncomposer require --dev voral/version-increment\n```\n\n### Usage\n\n```bash\n# Automatic detection of release type\n./vendor/bin/vs-version-increment\n\n# Incrementing the major version\n./vendor/bin/vs-version-increment major\n\n# Incrementing the minor version\n./vendor/bin/vs-version-increment minor\n\n# Incrementing the patch version\n./vendor/bin/vs-version-increment patch\n```\n\nUtility help command\n\n```bash\n./vendor/bin/vs-version-increment --help\n```\n\nRetrieving the list of registered commit types and registered scopes\n\n```bash\n./vendor/bin/vs-version-increment --list\n```\n\nExecute all file updates (e.g., CHANGELOG.md, composer.json) but skip creating the final Git commit and version tag\n\n```bash\n./vendor/bin/vs-version-increment --no-commit\n```\n\nThe `--debug` flag allows you to preview the changes that will be made to the CHANGELOG and version without actually\napplying them\n\n```bash\n# Automatic detection of release type\n./vendor/bin/vs-version-increment --debug\n\n# Incrementing the major version\n./vendor/bin/vs-version-increment --debug major\n\n# Incrementing the minor version\n./vendor/bin/vs-version-increment --debug minor\n\n# Incrementing the patch version\n./vendor/bin/vs-version-increment --debug patch\n```\n\nTo simplify usage, you can add scripts to `composer.json`:\n\n```json\n{\n  \"scripts\": {\n    \"vinc:major\": \"php ./vendor/bin/vs-version-increment major\",\n    \"vinc:minor\": \"php ./vendor/bin/vs-version-increment minor\",\n    \"vinc:patch\": \"php ./vendor/bin/vs-version-increment patch\",\n    \"vinc:auto\": \"php ./vendor/bin/vs-version-increment\",\n    \"vinc:list\": \"php ./vendor/bin/vs-version-increment --list\",\n    \"vinc:debug:auto\": \"php ./vendor/bin/vs-version-increment --debug\"\n  }\n}\n```\n\nExample of the output file:\n\n```markdown\n# 1.0.1 (2023-10-01)\n\n### Features\n\n- New endpoint user authentication\n- Added support dark mode\n\n### Fixes\n\n- Fixed a bug with login form validation\n- Resolved issue with incorrect API response\n\n### Other\n\n- Updated dependencies\n```\n\n## Configuration\n\nYou can configure the script by placing a `.vs-version-increment.php` file in the project directory and making the\nfollowing adjustments:\n\n- [Setting a Custom List of Change Types](docs/config.md#setting-a-custom-list-of-change-types)\n- [Configuring Change Types](docs/config.md#configuring-change-types)\n- [Configuring the Release Commit Type](docs/config.md#configuring-the-release-commit-type)\n- [Configuring the Main Repository Branch](docs/config.md#configuring-the-main-repository-branch)\n- [Configuring Types for Major Version Updates](docs/config.md#configuring-types-for-major-version-updates)\n- [Configuring Types for Minor Version Updates](docs/config.md#configuring-types-for-minor-version-updates)\n- [Release Scope Configuration](docs/config.md#release-scope-configuration)\n- [Custom Type Distribution Rules Setup](docs/config.md#custom-type-distribution-rules-setup)\n- [Ignoring Untracked Files](docs/config.md#ignoring-untracked-files)\n- [Configuring CHANGELOG Formatting](docs/config.md#configuring-changelog-formatting)\n    - [Using a Scope-Preserving Formatter](docs/config.md#using-a-scope-preserving-formatter)\n    - [Configuring Human-Readable Titles for Scopes](docs/config.md#configuring-human-readable-titles-for-scopes)\n    - [Creating a Custom Formatter](docs/config.md#creating-a-custom-formatter)\n- [Configuring Squashed Commits](docs/config.md#configuring-squashed-commits)\n    - [Default Squashed Commit](docs/config.md#default-squashed-commit)\n    - [Defining Squashed Commits via a Group](docs/config.md#defining-squashed-commits-via-a-group)\n    - [Combined Definition of a Squashed Commit](docs/config.md#combined-definition-of-a-squashed-commit)\n    - [General Rules for Full Commit Descriptions](docs/config.md#general-rules-for-full-commit-descriptions)\n- [Configuring the Commit Description Parser](docs/config.md#configuring-the-commit-description-parser)\n- [Disabling Version Updates in composer.json](docs/config.md#disabling-version-updates-in-composerjson)\n- [Sets a custom property in the configuration](docs/config.md#sets-a-custom-property-in-the-configuration)\n- [Suppress Duplicate Lines in CHANGELOG](docs/config.md#suppress-duplicate-lines-in-changelog)\n\n## Commit Descriptions\n\nFor the tool to function correctly, commit descriptions must follow this format:\n\n```\n\u003ctype\u003e[(scope)][!]: \u003cdescription\u003e\n\n[body]\n```\n\n- *type*: The commit type. It is recommended to use a predefined list for the project. Changes are grouped in the\n  changelog by type. Unregistered types fall under the default category. The type configured as related to new\n  functionality (default: `feat`) affects the minor version during automatic detection.\n- *scope* (optional): The project area to which the commit applies.\n- *!*: Indicates that the commit breaks backward compatibility. During automatic detection, this triggers a major\n  version update.\n- *description*: A short description.\n- *body*: Detailed description (not used by the tool).\n\nExamples:\n\n```\nfeat(router): New endpoint\n```\n\n```\ndoc: Described all features\n```\n\n```\nfeat!: Removed old API endpoints\n```\n\n## Default Commit Types\n\n| Type       | Purpose                                                      |\n|------------|--------------------------------------------------------------|\n| `feat`     | Adding new functionality                                     |\n| `fix`      | Fixing bugs                                                  |\n| `chore`    | Routine tasks (e.g., dependency updates)                     |\n| `docs`     | Documentation changes                                        |\n| `style`    | Code formatting (indentation, spaces, etc.)                  |\n| `refactor` | Refactoring code without adding new features or fixing bugs  |\n| `test`     | Adding or modifying tests                                    |\n| `perf`     | Performance optimization                                     |\n| `ci`       | Continuous integration (CI) configuration                    |\n| `build`    | Changes related to project build                             |\n| `other`    | All other changes that do not fall under standard categories |\n\n## CI/CD Integration\n\nThe script can be integrated into CI/CD pipelines. In case of errors, it returns different exit codes:\n\n| Code  | Description                           |\n|-------|---------------------------------------|\n| 10    | Composer configuration error          |\n| 20    | Git branch is not the main branch     |\n| 30    | Uncommitted changes in the repository |\n| 40    | No changes in the repository          |\n| 50    | Invalid configuration file            |\n| 60    | Error executing a Git command         |\n| 70    | Invalid version change type           |\n| 80    | Changelog File Error                  |\n| 90    | Unknown config property               |\n| 100   | Configuration is not set              |\n| 110   | Failed to retrieve files since tag    |\n| 500   | Other errors                          |\n| ≥5000 | User-defined custom errors            |\n\nYou can use it in the command line, for example:\n\n```bash\n./vendor/bin/vs-version-increment \u0026\u0026 echo 'Ok' || echo 'Error'\n```\n\nExample for GitHub Actions:\n\n```yaml\njobs:\n  version-update:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n\n      - name: Run version increment script\n        run: ./vendor/bin/vs-version-increment\n```\n\n## Event Handling with EventBus\n\nThe module includes an `EventBus` for handling events that occur during the utility's operation. This allows developers\nto create custom event handlers and extend the tool's functionality.\n\n### Key Features:\n\n- **Event Subscription**: Developers can subscribe to various events, such as the start of a version update, successful\n  completion, or error occurrence.\n- **Custom Event Handlers**: You can implement custom event handlers to perform additional actions, such as logging or\n  sending notifications. The handler must implement the `\\Vasoft\\VersionIncrement\\Contract\\EventListenerInterface`\n  interface.\n\n### Example Usage:\n\n```php\nuse Vasoft\\VersionIncrement\\Events\\EventType;\nuse Vasoft\\VersionIncrement\\Config;\nuse Vasoft\\VersionIncrement\\Contract\\EventListenerInterface;\nuse Vasoft\\VersionIncrement\\SemanticVersionUpdater;\n\nclass Listener implements EventListenerInterface {\n    public function handle(\\Vasoft\\VersionIncrement\\Events\\Event $event): void\n    {\n        print_r([\n            $event-\u003egetData(SemanticVersionUpdater::LAST_VERSION_TAG) ?? 'unknown',   \n            $event-\u003eeventType-\u003ename,        \n        ]);\n    }\n}\n$listener = new Listener();\n\n$config = new Config();\n\n$eventBus = $config-\u003egetEventBus();\n$eventBus-\u003eaddListener(EventType::BEFORE_VERSION_SET, $listener);\n$eventBus-\u003eaddListener(EventType::AFTER_VERSION_SET, $listener);\n$eventBus-\u003eaddListener(EventType::ON_ERROR, $listener);\n```\n\n### Available Event Types:\n\n| Event Type                  | Description                                                |\n|-----------------------------|------------------------------------------------------------|\n| `BEFORE_VERSION_SET`        | Triggered before the version update begins.                |\n| `AFTER_VERSION_SET_SUCCESS` | Triggered after the version update completes successfully. |\n| `AFTER_VERSION_SET_ERROR`   | Triggered when an error occurs.                            |\n\n### Recommendations:\n\n- Use `EventBus` to integrate third-party systems, such as monitoring or notification systems.\n- Ensure that your event handlers do not slow down the main execution process of the utility.\n\n## Error Handling for Custom Extensions\n\nWhen developing custom extensions or integrations for this tool, it is important to handle errors consistently and avoid\nconflicts with system-defined error codes. To achieve this, developers should use the `UserException` class for all\ncustom error scenarios.\n\n### Key Points:\n\n- **Reserved Error Codes**: The `UserException` class ensures that all user-defined error codes are offset by `5000`.\n  This guarantees that custom error codes do not overlap with system-defined codes (below `5000`).\n- **Usage Example**:\n  ```php\n  use Vasoft\\VersionIncrement\\Exceptions\\UserException;\n\n  throw new UserException(\n      code: 100, // Your custom error code (will be converted to 5100)\n      message: 'Custom error message describing the issue.'\n  );\n  ```\n- **Best Practices**:\n    - Use descriptive error messages to help users understand the cause of the error.\n    - Document the meaning of custom error codes in your extension's documentation.\n    - Avoid using error codes below `5000`, as these are reserved for system-defined errors.\n\nBy adhering to these guidelines, you can ensure seamless integration of your custom extensions with the tool while\nmaintaining clarity and consistency in error handling.\n\n## Configuration Examples\n\nTo help you get started with the library more quickly, I provide ready-to-use configuration examples for various use\ncases.\n\n### 1. Configuration for Keep a Changelog\n\nThis configuration example is designed for projects that follow the [Keep a Changelog](https://keepachangelog.com/)\nstandard. It organizes changes into categories (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`),\nmaking the changelog easy to read.\n\n-\n*File:* [`examples/keepachangelog.php`](https://github.com/Voral/vs-version-incrementor/blob/master/examples/keepachangelog.php)\n\n## Useful Links\n\n- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)\n- [Semantic Versioning](https://semver.org/)\n- [Project Repository](https://github.com/Voral/vs-version-incrementor)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoral%2Fvs-version-incrementor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoral%2Fvs-version-incrementor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoral%2Fvs-version-incrementor/lists"}