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
dotnet tool install --global Versionize
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
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"
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>
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.
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
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
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):".
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".
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
- 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