Skip to content

Latest commit

 

History

History
241 lines (169 loc) · 7.85 KB

README.md

File metadata and controls

241 lines (169 loc) · 7.85 KB
Raw

BizkitVersioningBundle

Latest Stable Version Build Status Code Coverage License

Symfony bundle which provides a way to version your application using various versioning strategies.

Showcase

Features

  • Stores the application's version & release date into a compliant YAML or XML Symfony container configuration file
  • Automatically imports the file with the parameters into Symfony's container
  • Supports multiple versioning strategies & creating custom ones
  • Includes a console command for incrementing the version using the configured versioning strategy
  • The command automatically commits the version file & optionally creates a tag if a VCS handler is configured
  • Supports the Git VCS & creating custom VCS handlers

Requirements

Installation

  1. Require the bundle using Composer:

    composer require bizkit/versioning-bundle

  2. Create a configuration file under config/packages/bizkit_versioning.yaml. Here's a reference configuration:

    bizkit_versioning:

    # The prefix added to the version parameters.
    parameter_prefix:     application # Example: my_app

    # The versioning strategy used.
    strategy:             incrementing

    # The name of the file containing the version information.
    filename:             version

    # The path to the file containing the version information.
    filepath:             '%kernel.project_dir%/config'

    # The format used for the version file.
    format:               yaml # One of "yaml"; "xml"

    # Configuration for the VCS integration,
    # set to false to disable the integration.
    vcs:

        # The handler used for the VCS integration,
        # set to null to disable the integration.
        handler:              git

        # The message to use for the VCS commit.
        commit_message:       'Update application version to %s'

        # The mode for applying tags to version commits:
        # - 'always': automatically add a tag without prompting
        # - 'never': do not add a tag
        # - 'ask': prompt before tagging when incrementing versions
        tagging_mode:         ask # One of "always"; "never"; "ask"

        # The message to use for the VCS tag.
        tag_message:          'Update application version to %s'

        # The name used for the VCS commit information,
        # set to null to use the default VCS configuration.
        name:                 null

        # The email used for the VCS commit information,
        # set to null to use the default VCS configuration.
        email:                null

        # The path to the VCS executable,
        # set to null for autodiscovery.
        path_to_executable:   null

  3. If your project doesn't use Symfony Flex, enable the bundle in config/bundles.php by adding it to the array:

    Bizkit\VersioningBundle\BizkitVersioningBundle::class => ['all' => true],

Usage

The bundle creates a compliant Symfony Dependency Injection Container configuration file with the following three parameters:

  • application.version - the application's version (the format depends on the configured versioning strategy)
  • application.version_hash - an MD5 digest of the version
  • application.release_date - an RFC 3339 formatted date on which the version was last incremented

NOTE: The parameter names mighty vary depending on the parameter_prefix configuration option.

It automatically adds the parameters into Symfony's container by registering the file as an import.

To find out more about parameters check Symfony's official documentation. The following example shows how to use it with Sentry's Monolog handler:

monolog:
    sentry:
        type: sentry
        dsn: '%sentry_dsn%'
        release: '%application.version%'

Incrementing the version

To increment the version using the configured strategy run the following command:

bin/console bizkit:versioning:increment

If you have a VCS handler configured, the command will automatically commit the version file & optionally create a tag with the new version.

Versioning strategies

The bundle comes with the following version strategies:

  1. incrementing - defines the version as an incrementing number
  2. semver - uses the Semantic Versioning system

Custom strategies

To implement a custom strategy all you need to do is create a service which implements the StrategyInterface interface.

namespace App;

use Bizkit\VersioningBundle\Strategy\StrategyInterface;

class MyStrategy implements StrategyInterface
{
    public function __invoke(StyleInterface $io, ?Version $version = null): Version
    {
        if (null === $version) {
            // return initial version
        }

        // return incremented version
    }
}

Use the FQCN of the service in the configuration:

bizkit_versioning:
    strategy: App\MyStrategy

If you are not using Symfony's autoconfigure feature or wish to use an alias in the configuration, tag the service with the bizkit_versioning.strategy tag.

App\MyStrategy:
    tags:
        - { name: 'bizkit_versioning.strategy', alias: 'my_strategy' }

bizkit_versioning:
    strategy: my_strategy

VCS handlers

The bundle comes with a handler for the Git VCS. If you wish to disable the VCS feature, set the vcs configuration option to false:

bizkit_versioning:
    vcs: false

Custom VCS handlers

To implement a custom VCS handler all you need to do is create a service which implements the VCSHandlerInterface interface.

namespace App;

use Bizkit\VersioningBundle\VCS\VCSHandlerInterface;

class MyVCSHandler implements VCSHandlerInterface
{
    public function commit(StyleInterface $io, Version $version): void
    {
        // commit the file
    }

    public function tag(StyleInterface $io, Version $version): void
    {
        // create a tag
    }
}

Use the FQCN of the service in the configuration:

bizkit_versioning:
    vcs:
        handler: App\MyVCSHandler

If you are not using Symfony's autoconfigure feature or wish to use an alias in the configuration, tag the service with the bizkit_versioning.vcs_handler tag.

App\MyVCSHandler:
    tags:
        - { name: 'bizkit_versioning.vcs_handler', alias: 'my_vcs' }

bizkit_versioning:
    vcs:
        handler: my_vcs

Versioning

This project follows Semantic Versioning 2.0.0.

Reporting Issues

Use the issue tracker to report any issues you encounter.

License

See the LICENSE file for details (MIT).