Versionize 2.0.0
See the version list below for details.
dotnet tool install --global Versionize --version 2.0.0
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local Versionize --version 2.0.0
#tool dotnet:?package=Versionize&version=2.0.0
nuke :add-package Versionize --version 2.0.0
Versionize
stop using weird build scripts to increment your nuget's version, use
versionize
!
Automatic versioning and CHANGELOG generation, using conventional commit messages.
how it works:
- when you land commits on your
main
branch, select the Squash and Merge option (not required). - add a title and body that follows the Conventional Commits Specification.
- when you're ready to release a nuget package:
git checkout main; git pull origin main
- run
versionize
git push --follow-tags origin main
dotnet pack
dotnet nuget push
versionize
does the following:
- bumps the version in your
.csproj
file (based on your commit history) - uses conventional-changelog to update CHANGELOG.md
- commits
.csproj
file and CHANGELOG.md - tags a new release
Installation
dotnet tool install --global Versionize
Usage
Usage: versionize [command] [options]
Options:
-?|-h|--help Show help information.
-v|--version Show version information.
-w|--workingDir <WORKING_DIRECTORY> Directory containing projects to version
--configDir <CONFIG_DIRECTORY> Directory containing the .versionize configuration file
-d|--dry-run Skip changing versions in projects, changelog generation and git commit
--skip-dirty Skip git dirty check
-r|--release-as <VERSION> Specify the release version manually
--silent Suppress output to console
--skip-commit Don't commit changes to the git repository
--skip-tag Don't tag the release commit
--skip-changelog Don't update the changelog
-i|--ignore-insignificant-commits Don't bump the version if no significant commits (fix, feat or BREAKING)
are found
--exit-insignificant-commits Exits with a non zero exit code if no significant commits (fix, feat or
BREAKING) are found
--commit-suffix Suffix to be added to the end of the release commit message (e.g. [skip ci])
-p|--pre-release Release as pre-release version with given pre release label.
-a|--aggregate-pre-releases Include all pre-release commits in the changelog since the last full version.
Only applies when new version is stable (non pre-release).
--find-release-commit-via-message Use commit message instead of tag to find last release commit.
--tag-only Don't read/write the version from/to project files. Depend on version tags only.
--proj-name Name of a project defined in the configuration file (for monorepos)
Commands:
inspect Prints the current version to stdout
Supported commit types
Every commit should be in the form
<type>[optional scope]: <description>
for example
fix(parser): remove colon from type and scope
- fix - will trigger a patch version increment in the next release
- feat - will trigger a minor version increment in the next release
- all other types - you can use any commit type but that commit type will not trigger a version increment in the next release
Breaking changes must contain a line prefixed with BREAKING CHANGE:
to allow versionize recognizing a breaking change. Breaking changes can use any commit type.
Example
git commit -m "chore: update dependencies" -m "BREAKING CHANGE: this will likely break the interface"
The happy versioning walkthrough
Preparation
Create a new project with the dotnet cli
mkdir SomeProject
dotnet new classlib
Ensure that a <Version> element is contained in file SomeProject.csproj
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<Version>1.0.0</Version>
</PropertyGroup>
</Project>
Using versionize
Now let's start committing and releasing
git init
...make some changes to "Class1.cs"
git add *
git commit -a -m "chore: initial commit"
versionize
Will add a CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj
will not change since this is your first release with versionize
.
...make some changes to "Class1.cs"
git commit -a -m "fix: something went wrong we need a bugfix release"
versionize
Will update CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj
is now 1.0.1
.
...make some changes to "Class1.cs"
git commit -a -m "feat: something really awesome coming in the next release"
versionize
Will update CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj
is now 1.1.0
.
...make some changes to "Class1.cs"
git commit -a -m "feat: a really cool new feature" -m "BREAKING CHANGE: the API will break. sorry"
versionize
Will update CHANGELOG.md, add git tags and commit everything. Note that the version in SomeProject.csproj
is now 2.0.0
since
versionize detected a breaking change since the commit note BREAKING CHANGE
was used above.
Pre-releases
Versionize supports creating pre-release versions by using the --pre-release
flag with a pre-release label, for example alpha
.
The following workflow illustrates how pre-release workflows with versionize work.
> git commit -a -m "chore: initial commit"
> versionize
// Generates version v1.0.0
> git commit -a -m "feat: some feature"
> versionize --pre-release alpha
// Generates version v1.1.0-alpha.0
> git commit -a -m "feat: some additional feature"
> versionize --pre-release alpha
// Generates version v1.1.0-alpha.1
> git commit -a -m "feat: some breaking feature" -m "BREAKING CHANGE: This is a breaking change"
> versionize --pre-release alpha
// Generates version v2.0.0-alpha.0
> versionize
// Generates version v2.0.0
Aggregated pre-releases changelog
By default, each commit message only appears in the release it was introduced. When using the pre-release feature this can result in a fragmented changelog. For example, when promoting to a full release the user has to browse through all the pre-release sections to see what's included.
v1.0.0-alpha.0
- featA
v1.0.0-alpha.1
- featB
v1.0.0
So to get around that you can pass the --aggregate-pre-releases
flag
versionize --pre-release alpha
versionize --pre-release alpha
versionize --aggregate-pre-releases
to get output like the following
v1.0.0-alpha.0
- featA
v1.0.0-alpha.1
- featB
v1.0.0
- featA
- featB
This also works together with the pre-release
option
versionize --pre-release alpha --aggregate-pre-releases
Skip pre-release tags
Some developers may prefer not to tag pre-releases. Here's an example of how to achieve that:
versionize --pre-release alpha --skip-tag
versionize --pre-release alpha --skip-tag --find-release-commit-via-message
...
find-release-commit-via-message
is necessary because Versionize uses git tags by default to determine the current version. Without a git tag, the way we determine which commits get included in the changelog is by searching for the last commit message that starts with "chore(release):".
Configuration
You can configure versionize
either by creating a .versionize
JSON file the working directory.
Any of the command line parameters accepted by versionize
can be provided via configuration file leaving out any -
. For example skip-dirty
can be provided as skipDirty
in the configuration file.
The .versionize
configuration file is deserialized into a FileConfig.cs
object behind the scenes.
Changelog customization can only be done via a .versionize
file. The following is an example configuration:
{
"changelogAll": true,
"changelog": {
"header": "My Changelog",
"sections": [
{
"type": "feat",
"section": "✨ Features",
"hidden": false
},
{
"type": "fix",
"section": "🐛 Bug Fixes",
"hidden": true
},
{
"type": "perf",
"section": "🚀 Performance",
"hidden": false
}
]
}
}
Because changelogAll
is true and the fix section is hidden, fix commits will appear in the a section titled "Other".
Developing
Want to do a PR and not care about setting up your development environment?
To get prettier test outputs run dotnet test
with prettier test logger
dotnet test --logger prettier
Roadmap
- [] Signed release commits
- [] Command to print out changelog entry since last release (as opposed to writing to a file)
- [] Tag prefix config (for non mono-repos)
- [] Add support for bumping a Unity project version
- [] Improve documentation
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
This package has no dependencies.
Version | Downloads | Last updated |
---|---|---|
2.3.0 | 3,626 | 11/9/2024 |
2.2.0 | 2,443 | 11/2/2024 |
2.1.0 | 4,553 | 10/20/2024 |
2.0.0 | 1,753 | 10/15/2024 |
1.27.0 | 39,569 | 6/15/2024 |
1.26.2 | 243 | 6/15/2024 |
1.26.1 | 223 | 6/15/2024 |
1.26.0 | 218 | 6/15/2024 |
1.25.0 | 11,965 | 5/5/2024 |
1.24.0 | 2,774 | 4/30/2024 |
1.23.0 | 2,296 | 4/29/2024 |
1.22.0 | 19,495 | 3/2/2024 |
1.21.0 | 32,870 | 11/3/2023 |
1.20.0 | 3,322 | 10/27/2023 |
1.19.1 | 9,893 | 9/16/2023 |
1.19.0 | 1,580 | 9/16/2023 |
1.18.0 | 42,959 | 3/11/2023 |
1.17.1 | 3,514 | 2/8/2023 |
1.17.0 | 4,845 | 12/23/2022 |
1.16.0 | 389 | 12/23/2022 |
1.15.2 | 7,203 | 10/4/2022 |
1.15.1 | 642 | 10/1/2022 |
1.15.0 | 34,961 | 6/26/2022 |
1.14.0 | 3,827 | 5/13/2022 |
1.13.0 | 1,327 | 3/13/2022 |
1.12.1 | 689 | 3/5/2022 |
1.12.0 | 553 | 2/26/2022 |
1.11.0 | 644 | 2/11/2022 |
1.10.0 | 628 | 1/5/2022 |
1.9.0 | 472 | 12/30/2021 |
1.8.0 | 3,765 | 10/5/2021 |
1.7.0 | 435 | 10/4/2021 |
1.6.2 | 3,386 | 1/9/2021 |
1.6.1 | 834 | 11/29/2020 |
1.6.0 | 618 | 11/29/2020 |
1.5.1 | 2,444 | 8/16/2020 |
1.4.0 | 579 | 8/11/2020 |
1.3.0 | 4,923 | 1/22/2020 |
1.2.0 | 1,516 | 12/18/2018 |
1.1.0 | 774 | 10/5/2018 |
1.0.0 | 820 | 9/29/2018 |