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:

1: 

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.

1: 
2: 

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

This will generate a structure similar to this

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21: 
22: 
23: 
24: 
25: 
26: 
27: 
28: 
29: 
30: 
31: 
32: 
33: 
34: 
35: 
36: 
37: 
38: 
39: 
40: 
41: 
42: 
43: 
44: 
45: 
46: 
47: 
48: 
49: 
50: 
51: 
52: 
53: 
54: 
55: 
56: 
57: 
58: 
59: 
60: 
61: 
62: 
63: 
64: 
65: 
66: 
67: 

.
├── CHANGELOG.md
├── Directory.Build.props
├── LICENSE.md
├── MyLib.1.sln
├── README.md
├── build
│   ├── build.fs
│   ├── build.fsproj
│   └── paket.references
├── build.cmd
├── build.sh
├── docsSrc
│   ├── Explanations
│   │   └── Background.md
│   ├── How_Tos
│   │   ├── Doing_A_Thing.md
│   │   └── Doing_Another_Thing.md
│   ├── Tutorials
│   │   └── Getting_Started.md
│   ├── content
│   │   ├── cleanups.js
│   │   ├── hotload.js
│   │   ├── style.css
│   │   ├── submenu.js
│   │   ├── themes.js
│   │   ├── tips.js
│   │   ├── toggle-bootstrap-dark.min.css
│   │   └── toggle-bootstrap.min.css
│   ├── files
│   │   └── placeholder.md
│   └── index.md
├── docsTool
│   ├── CLI.fs
│   ├── Prelude.fs
│   ├── Program.fs
│   ├── README.md
│   ├── WebServer.fs
│   ├── docsTool.fsproj
│   ├── paket.references
│   └── templates
│       ├── helpers.fs
│       ├── master.fs
│       ├── modules.fs
│       ├── namespaces.fs
│       ├── nav.fs
│       ├── partMembers.fs
│       ├── partNested.fs
│       └── types.fs
├── global.json
├── paket.dependencies
├── paket.lock
├── src
│   ├── Directory.Build.props
│   └── MyLib.1
│       ├── AssemblyInfo.fs
│       ├── Library.fs
│       ├── MyLib.1.fsproj
│       └── paket.references
└── tests
    ├── Directory.Build.props
    └── MyLib.1.Tests
        ├── AssemblyInfo.fs
        ├── Main.fs
        ├── MyLib.1.Tests.fsproj
        ├── Tests.fs
        └── paket.references

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.

  • ./src/MyCoolNewLib - This is where your library's source code will live.
  • ./tests/MyCoolNewLib.Tests - This is where your library's test code will live.
  • .\build.cmd or ./build.sh - Platform specific entry points into your build project.
  • ./build/ - The main build script of your repository.
  • ./README.md - The text file that introduces and explains a project.
  • ./CHANGELOG.md - Text file containing versioning, date, and release notes.

Building your library

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

1: 
2: 

./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:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 

---------------------------------------------------------------------
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 introductionary description.

Making a Release

The release process is streamlined so you only have to start your git repository, set your NuGet and GitHub authorization keys, create CHANGELOG notes, and run the Release build target.

1: 
2: 
3: 
4: 

git add .
git commit -m "Scaffold"
git remote add origin https://github.com/MyGithubUsername/MyCoolNewLib.git
git push -u origin master

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.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 

## [Unreleased]

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

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

## [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
  • You can then use the Release target, specifying the version number either in the RELEASE_VERSION environment variable, or else as a parameter after the target name. This will:
    • update CHANGELOG.md, moving changes from the Unreleased section into a new 0.2.0 section
      • if there were any prerelease versions of 0.2.0 in the changelog, it will also collect their changes into the final 0.2.0 entry
    • make a commit bumping the version: Bump version to 0.2.0 and adds the new changelog section to the commit's body
    • publish the package to NuGet
    • push a git tag
    • create a GitHub release for that git tag

macOS/Linux Parameter:

1: 

./build.sh Release 0.2.0

macOS/Linux Environment Variable:

1: 

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!