diff --git a/Terminal.Gui/README.md b/Terminal.Gui/README.md index 81d337f309..e1328bb1be 100644 --- a/Terminal.Gui/README.md +++ b/Terminal.Gui/README.md @@ -33,12 +33,12 @@ dotnet-gitversion The project version (the nuget package and in `Terminal.Gui.dll`) is determined from the latest `git tag`. -The format of version numbers is `vmajor.minor.patch.build.height` and follows the [Semantic Versioning](https://semver.org/) rules. +The format of version numbers is `vmajor.minor.patch.build` and follows the [Semantic Versioning](https://semver.org/) rules. To define a new version (e.g. with a higher `major`, `minor`, `patch`, or `build` value) tag a commit using `git tag`: ```powershell -git tag v1.3.4-beta.5 -a -m "Release v1.3.4 Beta 5" +git tag v1.2.3 -a -m "Release v1.2.3" dotnet-gitversion /updateprojectfiles dotnet build -c Release ``` @@ -47,23 +47,27 @@ dotnet build -c Release Doing so will update the `.csproj` files in your branch with version info, which we do not want. +## Automatic Nuget Publishing + +The following actions will publish the Terminal.Gui package to Nuget: + +* A new version tag is defined and pushed to `main` - this is the normal release process. +* A push to the `main` branch without a new version tag - this is a release-candidate build and will be of the form `1.2.3-rc.4` +* A push to the `develop` branch - this is a pre-release build and will be of the form `1.2.3-pre.4` + ## Publishing a Release of Terminal.Gui -First, use the [Semantic Versioning](https://semver.org/) rules.to determine the new verison number. +First, use the [Semantic Versioning](https://semver.org/) rules to determine the new version number. Given a version number MAJOR.MINOR.PATCH, increment the: * MAJOR version when you make incompatible API changes -* MINOR version when you add functionality in a backwards compatible manner -* PATCH version when you make backwards compatible bug fixes - -Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. +* MINOR version when you add functionality in a backward-compatible manner +* PATCH version when you make backwards-compatible bug fixes To release a new version (e.g. with a higher `major`, `minor`, or `patch` value) tag a commit using `git tag` and then push that tag directly to the `main` branch on `github.com/gui-cs/Terminal.Gui` (`upstream`). -The `tag` must be of the form `v..`, e.g. `v2.3.4`. - -`patch` can indicate pre-release or not (e.g. `pre`, `beta`, `rc`, etc...). +The `tag` must be of the form `v..`, e.g. `v1.2.3`. ### 1) Verify the `develop` branch is ready for release @@ -72,20 +76,22 @@ The `tag` must be of the form `v..`, e.g. `v2.3.4`. ### 2) Create a pull request for the release in the `develop` branch -The PR title should be of the form "Release v2.3.4" +The PR title should be of the form "Release v1.2.3" ```powershell git checkout develop git pull upstream develop git checkout -b v2_3_4 git add . -git commit -m "Release v2.3.4" +git commit -m "Release v1.2.3" git push ``` Go to the link printed by `git push` and fill out the Pull Request. -### 3) On github.com, verify the build action worked on your fork, then merge the PR +### 3) On github.com, verify the build action worked on your fork, then merge the PR to `develop` + +* Merging the PR will trigger the publish action on `upstream` (the main repo) and publish the Nuget package as a pre-release (e.g. `1.2.3-pre.1`). ### 4) Pull the merged `develop` from `upstream` @@ -104,20 +110,30 @@ git merge develop Fix any merge errors. +At this point, to release a release candidate, push the `main` branch `upstream` without a new tag. + +```powershell +git push upstream main +``` + +This will publish `1.2.3-rc.1` to Nuget. + ### 6) Create a new annotated tag for the release on `main` ```powershell -git tag v2.3.4 -a -m "Release v2.3.4" +git tag v1.2.3 -a -m "Release v1.2.3" ``` ### 7) Push the new tag to `main` on `upstream` ```powershell -git push --atomic upstream main v2.3.4 +git push --atomic upstream main v1.2.3 ``` *See https://stackoverflow.com/a/3745250/297526* +This will publish `1.2.3` to Nuget. + ### 8) Monitor Github Actions to ensure the Nuget publishing worked. https://github.com/gui-cs/Terminal.Gui/actions @@ -142,10 +158,6 @@ git push upstream develop https://www.nuget.org/packages/Terminal.Gui -When a new version tag is defined and merged into `main`, a Nuget package will be generated by a Github Action. - -If the version is pre-release (includes a hyphen, e.g. `1.3.4-beta.5`) the Nuget package will be tagged as pre-release. - Miguel & Tig can hide defunct/old Nuget packages. ## Contributing