Versionize 1.26.0
See the version list below for details.
dotnet tool install --global Versionize --version 1.26.0
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local Versionize --version 1.26.0
#tool dotnet:?package=Versionize&version=1.26.0
nuke :add-package Versionize --version 1.26.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 Skip commit and git tag after updating changelog and incrementing the
version
--skip-tag Skip git tag after making release commit
-i|--ignore-insignificant-commits Do not 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
--changelog-all Include all commits in the changelog not just fix, feat and breaking changes
--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).
--proj-version-bump-logic [DEPRECATED] Use --find-release-commit-via-message instead.
--find-release-commit-via-message Use commit message instead of tag to find last release commit.
--tag-only Only works with git tags, does not commit or modify the csproj file.
--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 --proj-version-bump-logic
proj-version-bump-logic
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 versionized
can be provided via configuration file leaving out any -
. For example skip-dirty
can be provided as skipDirty
in the configuration file.
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
- Pre Releases to allow creating beta.1, beta.2 versions
- Support .versionrc like "standard-version" does
- Support monorepo
-
--silent command line switch to suppress commandline output -
-i
,--ignore-insignificant-commits
command line switch to not create a new version if only insignificant (chore, ...) commits were done - GitHub URLs in changelog
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 is compatible. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. 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. |
.NET Core | netcoreapp3.1 is compatible. |
This package has no dependencies.
Version | Downloads | Last updated |
---|---|---|
1.27.0 | 22,927 | 6/15/2024 |
1.26.2 | 197 | 6/15/2024 |
1.26.1 | 171 | 6/15/2024 |
1.26.0 | 176 | 6/15/2024 |
1.25.0 | 11,836 | 5/5/2024 |
1.24.0 | 2,299 | 4/30/2024 |
1.23.0 | 1,870 | 4/29/2024 |
1.22.0 | 19,035 | 3/2/2024 |
1.21.0 | 32,500 | 11/3/2023 |
1.20.0 | 3,077 | 10/27/2023 |
1.19.1 | 9,805 | 9/16/2023 |
1.19.0 | 1,205 | 9/16/2023 |
1.18.0 | 41,819 | 3/11/2023 |
1.17.1 | 3,428 | 2/8/2023 |
1.17.0 | 4,800 | 12/23/2022 |
1.16.0 | 346 | 12/23/2022 |
1.15.2 | 6,473 | 10/4/2022 |
1.15.1 | 605 | 10/1/2022 |
1.15.0 | 29,766 | 6/26/2022 |
1.14.0 | 3,573 | 5/13/2022 |
1.13.0 | 1,290 | 3/13/2022 |
1.12.1 | 661 | 3/5/2022 |
1.12.0 | 517 | 2/26/2022 |
1.11.0 | 603 | 2/11/2022 |
1.10.0 | 589 | 1/5/2022 |
1.9.0 | 446 | 12/30/2021 |
1.8.0 | 3,473 | 10/5/2021 |
1.7.0 | 402 | 10/4/2021 |
1.6.2 | 3,345 | 1/9/2021 |
1.6.1 | 797 | 11/29/2020 |
1.6.0 | 573 | 11/29/2020 |
1.5.1 | 2,395 | 8/16/2020 |
1.4.0 | 540 | 8/11/2020 |
1.3.0 | 4,890 | 1/22/2020 |
1.2.0 | 1,488 | 12/18/2018 |
1.1.0 | 751 | 10/5/2018 |
1.0.0 | 796 | 9/29/2018 |