the-haive / flexversion Goto Github PK

Easy and flexible creation of version-strings (++) based on information from the git-repo (commits, merges and tags).

License: MIT License

C# 99.59% ANTLR 0.41%

git gitflow dotnet dotnet-standard dotnet-core semver tool build versioning

flexversion's Introduction

FlexVersion

This library/tool makes it easy to calculate very flexible version-strings (++) based on the repository commits and tags.

Concepts

Version Source

The version source is the commit that identifies the repo in regards to the state it is in. The tag name or the merge commit message can contain identifiers that help identify this, like i.e. 1.0.0-beta.12. The typical (and default config) use case is that tags and merges with that message will be used as a version-source.
Actions

When a version-source has been identified, the commits are played from oldest to newest and for each message the configuration allows you to perform increments (or decrements) on any of the detected parts from the version-source. Or you can create new parts that are counted. For instance, the default config adds "CommitCount", and then increments this on each commit/merge.
Output

At the end you usually want to create various output strings. These can be freely setup using any text, the above parts from the version-source, various other variables and functions.
Very flexible configration

No configuration options are default, they are all provided in the flexversion.yml file. The configuration system has all configuration options in separate branches, but all branches by default are setup to inherit from it. If you don't want to inherit then you can manipulate which parts you want to copy and not. The configuration file is written in YAML, which makes it very human friendly, and also host a lot of options for reusing config sections within the config-file.

Console app

The FlexVersion.exe (TODO) allows you to run this in a console. It can take additional input parameters to control which confguration-file to use, which repo to connect to and additional variables that you want to pass to the generated output strings. Run with help as option to see the usage.

Since the console project is created using .Net Core it can run on Linux, Mac and Windows full specification.

Library

The project core library, IntelliSearch.FlexVersion targets .NetStandard 2.0. This library can be used as a dll in your .Net project. This means that it can be used by a any .Net implementation that supports .Net Standard 2.0. At the time of writing this:

.Net Core 2.0+
.Net Framework 4.6.1+
Mono 5.4+
Xamarin.iOS 10.14+
Xamarin.Mac 3.8+
Xamarin.Android 8.0+
Universal Windows Platform 10.0.16299+

Ref: .NET Standard Implementation support

Getting started

At the moment you will have to clone the project, build it and then use the assemblies created. It is planned however to make this available on NuGet, Chocolatey and as a Cake addin.

Configuration

The settings-file is formatted via YAML and all configuration is added as items in the Branches section. The "*" entry is special, as this is the configuration that is used when a branch has no specific matches.

The suggested strategy (as used in the default config-file) is to add an entry per branch-type you use. I.e. master, support, release, feature, hotfix etc. The branches that has not been specified will use the "*" branch as fallback.

Have a look at the default configuration-file to get more details on the options available. It may look daunting at first sight, but it is fairly well documented and most of it are defaults that you may not want to change anyway.

Roadmap

Set up CI build and push to NuGet
Complete Cake addin
Handle pre-release label overrides via tag (and branch?). Specifically handy for release-candidates in GitFlow where the beta label is to be replaced with i.e. RC or RC1.
Write tests.

Disclaimer

This project is in beta state, and although it "works for me" it might not "work for you". If you find any issues or have any suggestions plese create an issue on the issue page. Or, if you want to contribute then that is super-cool too :).

Why not just use GitVersion?

I did this project instead of GitVersion because:

I could not get GitVersion to play the way I wanted it to.
Response on the project was slow.
It seems to be buggy for both the 3.x stable version as well as the 4.x beta. The CommitsSinceVersionSource counter seems to not do what I would have thought that it did.
I could not find out how to add increment for the pre-counter for every commit for pre-release info.
It is dead-slow, even when you are runing it on a repo where the current commit has a tag that dictates the version. It sometimes takes many minutes to figure out the version.
It sometimes fails and crashes, without me having been able to figure out the issues.
Response on the project on GitHub seems slow. Not sure if it is being maintained.

Now, all the issues I was having could be me doing something wrong in the configuration. While looking into things I got my own idea on how to approach this and that is what triggered this project.

License

FlexVersion is provided as-is under the MIT license. For more information see LICENSE.

flexversion's People

Contributors

Stargazers

Watchers

flexversion's Issues

Create/publish getting started video on YouTube

Setup app-veyor (or similar)

What is needed to build dotnet core stuff?
Can I build executables for any target?

Have the cake addin listed on Cake

Create website for the project

separate nice page, squarespace?

Set up Cake build

Load itself from NuGet
This will work after first package has been published. Will always use an older version to version itself, but - that is ok...

Allow fallback-version to be configured (with override option in API)

Currently if the version-source is not found it fails. We should instead use a fallback value that defaults to 0.0.0.

Also, the configured fallback should be allowed to be overridden from the API.

Allow the git commit-log to be constrained by given paths

With this feature in place only git commits touching code within the given paths is considered a potential version source.

The "given paths" will in practical terms be the paths that a given project within the repo uses for it's files. The reason for allowing multiple paths, is that in C# a project may have other project references that also live in the same repo. A change in a dependent project should also count as a commit for the consuming project. To be seen in context of the changes suggested in #17.

Add support for boolean expressions in the parser

Add support for using `args` and `env` in the configuration strings

This will allow FlexVersion to be called i.e. once per project, with i.e. arg Project=MyProject, so that the match regex for the VersionSource will match only for tags prefixed with "MyProject-". We should inject these into the match regex via a simple replacement, like for instance $Arg:Project, or $Env:Project.

This feature will often be used in combination with feature #19 to constrain the git log to given paths only. This is useful for cases where individual parts of a repo is to have separate versioning.

Write article on Medium

Marketing

Create website for the project (separate nice page, squarespace?)
Write article on Medium
Create video for YouTube
Create tag on StackOverflow

Add documentation

Will be using DocFX for this to:

Generate product documentation from markdown documents.
Generate API-documentation by scanning libraries.

Refactor functions and variables

Only previous outputs are to be in angle-brackets, <>

Function-list:

   string $If(bool expression, string then, string else)
   string $IfNot(bool expression, string then, string else)

   string $IfBlank(string text, string then, string else)
   string $IfNotBlank(string text, string then, string else)

   bool $Equal(dynamic a, dynamic b)
   bool $NotEqual(dynamic a, dynamic b)

   number $Index(original, toFind)
   number $IndexLast(original, toFind)

   number $Length(text)

   number $Calc(string numericExpression)

   bool $RegexMatch(input, pattern)
   string $RegexReplace(original, regex, replacementText)

   string $PadLeft(string text, int totalLength, char padCharacter)
   string $PadRight(string text, int totalLength, char padCharacter)

   string $Substring(string text, int startIndex, int stopIndex)

   string $Trim(string input)
   string $TrimRight(string input)
   string $TrimLeft(string input)

   string $DateTime(string input, string format)
   string $DateTimeNow(string format)

   string $Env(string identifier)
   string $Arg(string identifier)
   string $Match(string identifier)
   string $VersionSource(string identifier)
   string $GitInfo(string identifier)
   string $Head(string identifier)

Push library to NuGet

During build, create and push library package to NuGet.org
During build, create and push Cake Addin library to NuGet.org

Add support for mapping LibLog messages to Cake in the addin

Existing LogProviders: https://github.com/damianh/LibLog/tree/master/src/LibLog/LogProviders
Sample: https://gist.github.com/damianh/fa529b8346a83f7f49a9#file-liblogmsowinlogging-cs-L23-L72
Sample: https://github.com/damianh/LibLog/blob/master/src/LibLog.Example.ColoredConsoleLogProvider/ColoredConsoleLogProvider.cs
LibLog gitter: August 21, 2018 11:30 AM

Push executable to chocolatey

During build, create windows version and publish to chocolatey.
During build, TODO: How to create linux/mac version and publish where?