Updated 2020-09-17 09:29
Added GitHub CLI commands to create labels instead of doing it manually.
Updated 2020-09-08 09:46
The GitHub CLI simplified some commands, so I've updated the post to make use of those simpler commands.
Updated 2020-07-08 12:16
I forgot to mention how we can use labels to help automatically draft release notes, so I've updated the post with a few extra screenshots and descriptions.
So, you want to publish a new NuGet package? You just want to get your code up into nuget.org as quickly as possible but there is so much that you have to setup to get there. Not any more! I'll show you how you can create a new project and publish a NuGet package with all the bells and whistles in a couple of minutes.
We'll start off by creating a new GitHub repository using the new GitHub CLI.
gh repo create RehanSaeed/FastestNuGet --public --confirm cd FastestNuGet
The next step is to install the Dotnet Boxed project templates and then create a new project using the NuGet template. There is a lot of optional features you can toggle in this project template which you can review by looking at the output for the
dotnet new nuget --help command.
dotnet new --install Boxed.Templates dotnet new nuget --help dotnet new nuget --name FastestNuGet --title "Project Title" --description "Project Description" --github-username RehanSaeed --github-project FastestNuGet
Next we'll commit and push our newly created project to the
git add . git commit -m "Initial" git push --set-upstream origin master
As soon as we do this, we'll see two GitHub Actions have started.
Build GitHub Action has completed several actions you can see below. Note that these actions were completed on Windows, MacOS and Ubuntu Linux. This ensures that your code builds and passes tests on all platforms.
This resulted in a NuGet package being packaged up and pushed to GitHub packages. This is a nice place to store pre-release packages that you can use for testing.
Release Drafter GitHub action created a draft release for us in GitHub releases.
Next we need to create some default labels that we can apply to pull requests. This will help us create automatic release notes for any NuGet packages we release. The
maintenance labels will categorise changes in our release notes. The
patch labels will automatically generate a semantic versioning 2.0 compliant version number for us.
I've gone in to GitHub and deleted all the existing labels and then run a few GitHub CLI commands to create just the ones I want:
gh api --silent repos/:owner/:repo/labels -f name="bug" -f description="Issues describing a bug or pull requests fixing a bug." -f color="ee0701" gh api --silent repos/:owner/:repo/labels -f name="enhancement" -f description="Issues describing an enhancement or pull requests adding an enhancement." -f color="a2eeef" gh api --silent repos/:owner/:repo/labels -f name="maintenance" -f description="Pull requests that perform maintenance on the project but add no features or bug fixes." -f color="fff89b" gh api --silent repos/:owner/:repo/labels -f name="major" -f description="Pull requests requiring a major version update according to semantic versioning." -f color="b23021" gh api --silent repos/:owner/:repo/labels -f name="minor" -f description="Pull requests requiring a minor version update according to semantic versioning." -f color="f99248" gh api --silent repos/:owner/:repo/labels -f name="patch" -f description="Pull requests requiring a patch version update according to semantic versioning." -f color="eaf42c"
Now it's time to make a change and submit a new pull request (PR) to our repository. Notice I'm adding a
enhancement label to the pull request.
git switch --create some-change git add . git commit -m "Some change" git push --set-upstream origin some-change gh pr create --fill --label major --label enhancement
Next, I'll check that the pull request passed all eight of it's continuous integration build checks and merge the pull request.
If we go back to GitHub Releases, we'll see that our draft GitHub release was automatically updated with details of our pull request! Notice that the
enhancement label also caused our pull request to be categorised under 'New Features'.
Next, we'll want to publish an official release of our NuGet package to nuget.org but first, we need to get hold of a NuGet API key from nuget.org and add it as a secret named
NUGET_API_KEY in GitHub secrets.
Finally I'll edit the release and change the tag name and display name for the release to
1.0.0. Normally, the
patch labels we applied earlier would generate this version for us but this is the first ever Git tag, so we'll need to do it ourselves.
In my last post 'The Easiest Way to Version NuGet Packages' I talked more about how we are using MinVer for taking the Git tags and versioning our DLL's and NuGet packages.
Now bask in the glory of seeing your NuGet package on nuget.org. I also just noticed there is a Black Lives Matter (BLM) banner on the site! Those lives certainly do matter, check out my recent post on Racism in Software Development and Beyond for my take on the subject.
That's not all! We didn't just push one NuGet package, we also pushed it's symbols to the nuget.org symbol server. The NuGet package is also signed and has source link support, so developers can debug code in your NuGet package. If you look at the main ReadMe of your project, you'll see a badge showing you the status of the latest GitHub Action run on the master branch and finally you also see a graph showing you how long each GitHub Action run took and it's status over time.
You can take a look at the repository at RehanSaeed/FastestNuGet to see all of the above in action.
The Complete Script
Here is the complete script we ran to get from starting a new project to publishing on NuGet. I took lots of screenshots along the way but overall, you can do all this in about two minutes assuming you have everything installed.
gh repo create RehanSaeed/FastestNuGet --public --confirm cd FastestNuGet dotnet new --install Boxed.Templates dotnet new nuget --name FastestNuGet --title "Project Title" --description "Project Description" --github-username RehanSaeed --github-project FastestNuGet git add . git commit -m "Initial" git push --set-upstream origin master # View GitHub Actions Continuous Integration Build start "https://github.com/RehanSaeed/FastestNuGet/actions" # View NuGet Package Published to GitHub Packages start "https://github.com/RehanSaeed/FastestNuGet/packages" # Create major, minor, patch, bug, enhancement, maintenance labels start "https://github.com/RehanSaeed/FastestNuGet/labels" git switch --create some-change git add . git commit -m "Some change" git push --set-upstream origin some-change gh pr create --fill --label major --label enhancement # View and Complete Pull Request start "https://github.com/RehanSaeed/FastestNuGet/pull/1" # Add NUGET_API_KEY to GitHub Secrets start "https://github.com/RehanSaeed/FastestNuGet/settings/secrets" # View and Publish Updated Draft Release start "https://github.com/RehanSaeed/FastestNuGet/releases" # View NuGet Package Published to NuGet start "https://www.nuget.org/packages/FastestNuGet/"
I hope this Dotnet Boxed project template accelerates development of your next NuGet package. There are lots of optional features of the NuGet project template I haven't even shown like support for Azure Pipelines and Appveyor continuous integration builds and more, so please do go and take a look.