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
- 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
Installing MiniScaffold
Install the dotnet template from NuGet:
1:
|
|
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: |
|
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.cmd
or./build.sh
- Platform specific entry points into yourbuild
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: |
|
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_TOKEN
to your key
-
-
You can then set the
GITHUB_TOKEN
to uploadCHANGELOG
notes and artifacts to githubIf 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.
RELEASE
target 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
Release
target, specifying the version number either in theRELEASE_VERSION
environment variable, or else as a parameter after the target name. This will:-
update
CHANGELOG.md
, moving changes from theUnreleased
section into a new0.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
-
update
macOS/Linux Parameter:
1:
|
|
macOS/Linux Environment Variable:
1:
|
|
Done
You have now successfully created your first OSS library that has been published to NuGet and GitHub. Congratulations!