In this tutorial, we'll take a look at getting started with MiniScaffold and publishing your first library to NuGet and GitHub
- Install git
- Install .Net core
- If on macOS or Linux, install Mono
- If on Windows ensure you have at least .NET Full Framework 4.6.1 installed
- Recommended IDE is VSCode with Ionide
- Create a NuGet account
- Create a GitHub account
Install the dotnet template from NuGet:
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.
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:
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.sh- Platform specific entry points into your
./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:
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:
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:
or set the environment variable
NUGET_TOKENto your key
You can then set the
CHANGELOGnotes and artifacts to github
If you're on a linux, you can put this key into your .bashrc
- Otherwise it will fallback to username/password
Then update the
CHANGELOG.md with an "Unreleased" section containing release notes for this version, in KeepAChangelog format.
RELEASEtarget is run, it will add these new notes into the body of git commit. GitHub will notice the links and will update the Pull Request with what commit referenced it saying "added a commit that referenced this pull request". Since we automate the commit message, it will say "Bump Version to x.y.z". The benefit of this is when users goto a Pull Request, it will be clear when and which version those code changes released. Also when reading the
CHANGELOG, if someone is curious about how or why those changes were made, they can easily discover the work and discussions.
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:
You can then use the
Releasetarget, specifying the version number either in the
RELEASE_VERSIONenvironment variable, or else as a parameter after the target name. This will:
CHANGELOG.md, moving changes from the
Unreleasedsection into a new
- 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.0and 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 Environment Variable:
You have now successfully created your first OSS library that has been published to NuGet and GitHub. Congratulations!