Skip to content

Latest commit

 

History

History
137 lines (111 loc) · 7.88 KB

readme.md

File metadata and controls

137 lines (111 loc) · 7.88 KB

dotnet-releaser Build Status NuGet

dotnet-releaser is an all-in-one command line tool that fully automates the release cycle of your .NET libraries and applications to NuGet and GitHub by building, testing, running coverage, cross-compiling, packaging, creating release notes from PR/commits and publishing.

In practice, dotnet-releaser will automate the build and publish process of your .NET libraries and applications by wrapping:

  • dotnet build with potentially multiple solutions
  • dotnet test
    • Plus the automatic support for coverage.
  • dotnet pack for creating NuGet packages
  • dotnet publish that can automatically cross-compile to 9+ CPU/OS platforms.
    • And create additionally, by default, multiple packages (zip, debian, rpm...) to distribute your app
  • dotnet nuget push to publish your package to a NuGet registry
  • Pretty changelog creation from pull-requests and commits.
  • Create and upload the changelog and all the packages packed to your GitHub repository associated with the release tag.
  • It can publish automatically the coverage results to a badge in a GitHub gist or to https://coveralls.io if your repository is created there.

overview

Features

  • Very simple to use, configure and integrate into your GitHub Action CI
  • Build and tests your .NET libraries and applications from multiple solutions.
  • Add automatic coverage support via coverlet with your tests.
  • Cross-compile your .NET 6.0+ application to 9+ OS/CPU targets.
  • Create zip archives, Linux packages (debian, rpm) and Homebrew taps
  • Allow to publish your application as a service (only Systemd for now for deb and rpm packages).
  • Create and publish beautiful release notes by extracting the information directly from pull-requests and commits, while offering customizable templates.
  • Publish all artifacts to NuGet and GitHub
  • Can be used to build/tests/package/publish locally or from GitHub Action using the same command.

Defaults

By default, dotnet-releaser will:

  • Build your project(s)/solution(s) in Release
  • Run tests in Release
  • Create NuGet packages for libraries and applications (packed as a .NET global tool)
  • Create application packages for any packable application in your project:
    Platform Packages
    win-x64, win-arm, win-arm64 zip
    linux-x64, linux-arm, linux-arm64 deb, tar
    rhel-x64 rpm, tar
    osx-x64, osx-arm64 tar
  • Publish libraries and/or applications to NuGet
  • Upload all the package artifacts and your changelog to GitHub on the tag associated with your package version (e.g your package is 1.0.0, it will try to find a git tag v1.0.0 or 1.0.0).
  • Create a Homebrew repository and formula (e.g user_or_org/homebrew-your-app-name) for all the tar files associated with the targets for Linux and MacOS.

Any of these steps can be configured or even entirely disabled easily from a config file. See the user guide on how to setup this differently for your application.

Getting Started

  • Install dotnet-releaser as a global .NET tool.
    dotnet tool install --global dotnet-releaser
    
  • Go to a folder where you have your solution .sln file or your project file (.csproj, .fsproj, .vbproj) and run:
    dotnet releaser new
    
  • It should create a dotnet-releaser.toml at the same level than your solution with a content like:
    [msbuild]
    project = "Tonlyn.sln"
    [github]
    user = "xoofx"
    repo = "Tomlyn"
  • If you want to try a full build locally:
    dotnet-releaser build --force dotnet-releaser.toml
    
  • If you want to integrate it to GitHub Action, use the dotnet-releaser run command. More details in the doc Adding dotnet-releaser to your CI on GitHub. It is no more complicated than adding the following lines in your GitHub workflow file:
      steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
    
      - name: Install .NET 7.0
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '7.0.x'
    
      - name: Build, Tests, Cover, Pack and Publish (on push tag)
        shell: bash
        run: |
          dotnet tool install --global dotnet-releaser
          dotnet-releaser run --nuget-token "${{secrets.NUGET_TOKEN}}" --github-token "${{secrets.GITHUB_TOKEN}}" src/dotnet-releaser.toml
    Notice the recommended usage of shell: bash so that if a secrets token is empty, bash won't remove the quotes, unlike pwsh.

See the user guide below for further details on how to use dotnet-releaser.

User Guide

For more details on how to use dotnet-releaser, please visit the user guide.

License

This software is released under the BSD-Clause 2 license.

Who is using dotnet-releaser?

It's brand new, so it's mainly used by the author for now! 😇

You can visit the .github/workflows folder, or check the release notes of the following projects to see dotnet-releaser in action:

Applications:

  • grpc-curl: An application shipping multiple executables.
  • lunet: An application shipping a .NET global tool to NuGet.

Regular .NET Libraries:

Credits

dotnet-releaser is a wrapper around many amazing OSS libraries:

Author

Alexandre Mutel aka xoofx.