MiniScaffold 0.40.0-beta001

Edit this page

Getting Started

In this tutorial, we'll take a look at getting started with MiniScaffold and publishing your first library to NuGet and GitHub.

Prerequisites

Installing MiniScaffold

Install the dotnet template from NuGet:

dotnet new -i "MiniScaffold::*"

Then use the template to create your own library. Replace MyCoolNewLib with your own library name and MyGithubUsername with your own GitHub name. If you have trouble picking a library name then generate one.

dotnet new mini-scaffold -n MyCoolNewLib --githubUsername MyGithubUsername
cd MyCoolNewLib

This will generate a structure similar to this

.
├── CHANGELOG.md
├── Directory.Build.props
├── Directory.Build.targets
├── LICENSE.md
├── README.md
├── build
│   ├── Changelog.fs
│   ├── FsDocs.fs
│   ├── build.fs
│   ├── build.fsproj
├── build.cmd
├── build.sh
├── docsSrc
│   ├── Explanations
│   │   └── Background.md
│   ├── How_Tos
│   │   ├── Doing_A_Thing.md
│   │   └── Doing_Another_Thing.md
│   ├── Tutorials
│   │   └── Getting_Started.md
│   ├── _menu-item_template.html
│   ├── _menu_template.html
│   ├── _template.html
│   ├── content
│   │   ├── fsdocs-custom.css
│   │   ├── fsdocs-dark.css
│   │   ├── fsdocs-light.css
│   │   ├── fsdocs-main.css
│   │   ├── navbar-fixed-left.css
│   │   └── theme-toggle.js
│   └── index.md
├── global.json
├── MyCoolNewLib.sln
├── src
│   ├── Directory.Build.props
│   └── MyCoolNewLib
│       ├── AssemblyInfo.fs
│       ├── Library.fs
│       ├── MyCoolNewLib.fsproj
└── tests
    ├── Directory.Build.props
    └── MyCoolNewLib.Tests
        ├── Main.fs
        ├── Tests.fs
        ├── MyCoolNewLib.Tests.fsproj

This may look overwhelming, but we don't have to worry about all of these yet. Let's just focus on the real important ones for this tutorial.

Building your library

To make sure everything is functioning correctly, run the build command for your platform:

./build.sh //for macOS or Linux
.\build.cmd \\for Windows

You'll be flooded with a screen full of text, documenting the build processes at it currently stands. If it completes successfully you should be greeted with something similar:

---------------------------------------------------------------------
Build Time Report
---------------------------------------------------------------------
Target                   Duration
------                   --------
Clean                    00:00:00.0180266
DotnetRestore            00:00:08.1013232
DotnetBuild              00:00:09.2786467
DotnetTest               00:00:07.9084110
GenerateCoverageReport   00:00:00.8499974
DotnetPack               00:00:06.3346539
Total:                   00:00:32.6192299
Status:                  Ok
---------------------------------------------------------------------

This is FAKE telling us everything that ran, how long, and if it completed successfully.

If it does not complete successfully, either open an issue or ask on F# Slack.

Fill out README.md

The README.md comes with a lot of information but it's recommended to fill out the introduction description.

Making a Release

Create your GitHub repository and configure NuGet trusted publishing before the first release. For each release, add CHANGELOG notes and run the Release build target.

Create your Github Repository

Configure trusted publishing

  1. Create a GitHub environment named nuget if it does not exist.
  2. Open NuGet trusted publishing.
  3. Create a policy with the correct NuGet package owner and package scopes.
  4. Set the GitHub owner to your actual GitHub username or organization.
  5. Set the repository to MyCoolNewLib, or its actual name if you renamed it.
  6. Set the workflow filename to publish.yml and the environment to nuget.
  7. Add an environment variable named NUGET_USER in the GitHub nuget environment.
  8. Set the variable to the policy creator's actual NuGet profile name.

Do not use an email address or assume that the NuGet profile matches the GitHub owner. NuGet/login@v1 supplies the API key through the existing NUGET_TOKEN build input. The workflow has no stored-key fallback.

After an authorized tag-triggered release, verify the NuGet package version and GitHub release artifacts. Check the complete run logs for credentials and credential fragments. Check that NuGet reports the policy as active and permanent. Only after all verification succeeds, remove the stored GitHub NUGET_TOKEN secret and revoke the old scoped NuGet key. Keep both credentials until these checks pass. Use the release guide for detailed setup, failure checks, and manual emergency recovery.

Prepare your CHANGELOG.md

Then update the CHANGELOG.md with an "Unreleased" section containing release notes for this version, in KeepAChangelog format.

Here's an example of adding an Unreleased section to a CHANGELOG.md with a 0.1.0 section already released.

## [Unreleased]

### Added
- Does cool stuff! (https://github.com/MyGithubUsername/MyCoolNewLib/pull/001) (Thanks @TheAngryByrd!)

### Fixed
- Fixes that silly oversight (https://github.com/MyGithubUsername/MyCoolNewLib/pull/002) (Thanks! @baronfel)

## [0.1.0] - 2017-03-17
First release

### Added
- This release already has lots of features

[Unreleased]: https://github.com/user/MyCoolNewLib.git/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/MyCoolNewLib.git/releases/tag/v0.1.0

macOS/Linux Parameter:

./build.sh Release 0.2.0

macOS/Linux Environment Variable:

RELEASE_VERSION=0.2.0 ./build.sh Release

Done

You have now successfully created your first OSS library that has been published to NuGet and GitHub. Congratulations!