diff --git a/Content/.template.config/ide.host.json b/Content/.template.config/ide.host.json index 99d8bd28..0796821a 100644 --- a/Content/.template.config/ide.host.json +++ b/Content/.template.config/ide.host.json @@ -1,5 +1,5 @@ { - "$schema": "http://json.schemastore.org/vs-2017.3.host", + "$schema": "https://json.schemastore.org/vs-2017.3.host", "symbolInfo": [ { "id": "githubUsername", @@ -10,17 +10,17 @@ }, { "id": "outputType", - "name" : { + "name": { "id": "outputType", "text": "Output Type" } }, { "id": "releaseBranch", - "name" : { + "name": { "id": "releaseBranch", "text": "Release Branch" } } ] -} +} \ No newline at end of file diff --git a/Content/.template.config/template.json b/Content/.template.config/template.json index 86be27a5..bf97eb41 100644 --- a/Content/.template.config/template.json +++ b/Content/.template.config/template.json @@ -1,8 +1,10 @@ { - "$schema": "http://json.schemastore.org/template", + "$schema": "https://json.schemastore.org/template", "author": "Jimmy Byrd", "classifications": [ - "Scaffold", "Console", "Library" + "Scaffold", + "Console", + "Library" ], "description": "A full-featured template for creating console or library solutions with documentation and release workflows.", "name": "MiniScaffold", @@ -28,11 +30,23 @@ "choices": [ { "choice": "library", - "description": "Creates a template for library projects" + "description": "Creates a template for library solutions." }, { "choice": "console", - "description": "Creates a template for console projects" + "description": "Creates a template for console solutions." + }, + { + "choice": "projLib", + "description": "A project for creating a class library. Used for creating individual library projects for MiniScaffold." + }, + { + "choice": "projConsole", + "description": "A project for creating a command-line application. Used for creating individual console projects for MiniScaffold." + }, + { + "choice": "projTest", + "description": "A project for Expect tests. Used for creating individual test projects for MiniScaffold." } ] }, @@ -53,6 +67,21 @@ "source": "./Console/", "target": "./", "condition": "(outputType == \"console\")" + }, + { + "source": "./ProjLib/", + "target": "./", + "condition": "(outputType == \"projLib\")" + }, + { + "source": "./ProjConsole/", + "target": "./", + "condition": "(outputType == \"projConsole\")" + }, + { + "source": "./ProjTest/", + "target": "./", + "condition": "(outputType == \"projTest\")" } ], "postActions": [ @@ -71,4 +100,4 @@ "continueOnError": true } ] -} +} \ No newline at end of file diff --git a/Content/Console/build/Changelog.fs b/Content/Console/build/Changelog.fs index fe84b5a0..b9af45f0 100644 --- a/Content/Console/build/Changelog.fs +++ b/Content/Console/build/Changelog.fs @@ -28,7 +28,11 @@ let isChangelogEmpty (latestEntry: Changelog.ChangelogEntry) = let tagFromVersionNumber versionNumber = sprintf "%s" versionNumber -let mkLinkReference (newVersion: SemVerInfo) (changelog: Changelog.Changelog) gitHubRepoUrl = +let mkLinkReference + (newVersion: SemVerInfo) + (changelog: Changelog.Changelog) + (gitHubRepoUrl: string) + = if changelog.Entries |> List.isEmpty @@ -37,7 +41,7 @@ let mkLinkReference (newVersion: SemVerInfo) (changelog: Changelog.Changelog) gi sprintf "[%s]: %s/releases/tag/%s" newVersion.AsString - gitHubRepoUrl + (gitHubRepoUrl.TrimEnd('/')) (tagFromVersionNumber newVersion.AsString) else let versionTuple version = diff --git a/Content/Console/build/build.fs b/Content/Console/build/build.fs index 6425bcd3..22a869cc 100644 --- a/Content/Console/build/build.fs +++ b/Content/Console/build/build.fs @@ -113,7 +113,7 @@ let coverageReportDir = let gitOwner = "MyGithubUsername" let gitRepoName = "MyLib.1" -let gitHubRepoUrl = sprintf "https://github.com/%s/%s" gitOwner gitRepoName +let gitHubRepoUrl = sprintf "https://github.com/%s/%s/" gitOwner gitRepoName let releaseBranch = "MyReleaseBranch" diff --git a/Content/Library/build/Changelog.fs b/Content/Library/build/Changelog.fs index bea9e0d3..2efcb0a3 100644 --- a/Content/Library/build/Changelog.fs +++ b/Content/Library/build/Changelog.fs @@ -27,7 +27,11 @@ let failOnEmptyChangelog (latestEntry: Changelog.ChangelogEntry) = failwith "No changes in CHANGELOG. Please add your changes under a heading specified in https://keepachangelog.com/" -let mkLinkReference (newVersion: SemVerInfo) (changelog: Changelog.Changelog) gitHubRepoUrl = +let mkLinkReference + (newVersion: SemVerInfo) + (changelog: Changelog.Changelog) + (gitHubRepoUrl: string) + = if changelog.Entries |> List.isEmpty @@ -36,7 +40,7 @@ let mkLinkReference (newVersion: SemVerInfo) (changelog: Changelog.Changelog) gi sprintf "[%s]: %s/releases/tag/%s" newVersion.AsString - gitHubRepoUrl + (gitHubRepoUrl.TrimEnd('/')) (tagFromVersionNumber newVersion.AsString) else let versionTuple version = diff --git a/Content/Library/build/build.fs b/Content/Library/build/build.fs index c4f999a6..4ca63142 100644 --- a/Content/Library/build/build.fs +++ b/Content/Library/build/build.fs @@ -104,7 +104,7 @@ let watchDocsDir = let gitOwner = "MyGithubUsername" let gitRepoName = "MyLib.1" -let gitHubRepoUrl = sprintf "https://github.com/%s/%s" gitOwner gitRepoName +let gitHubRepoUrl = sprintf "https://github.com/%s/%s/" gitOwner gitRepoName let documentationRootUrl = sprintf "https://%s.github.io/%s/" gitOwner gitRepoName diff --git a/Content/ProjConsole/AssemblyInfo.fs b/Content/ProjConsole/AssemblyInfo.fs new file mode 100644 index 00000000..d1613d7d --- /dev/null +++ b/Content/ProjConsole/AssemblyInfo.fs @@ -0,0 +1,23 @@ +// Auto-Generated by FAKE; do not edit +namespace System +open System.Reflection + +[] +[] +[] +[] +[] +[] +[] +[] +do () + +module internal AssemblyVersionInformation = + let [] AssemblyTitle = "MyLib.1" + let [] AssemblyProduct = "MyLib.1" + let [] AssemblyVersion = "0.1.0" + let [] AssemblyMetadata_ReleaseDate = "2017-03-17T00:00:00.0000000" + let [] AssemblyFileVersion = "0.1.0" + let [] AssemblyInformationalVersion = "0.1.0" + let [] AssemblyMetadata_ReleaseChannel = "release" + let [] AssemblyMetadata_GitHash = "b385af579477bb585016a6b5204121de4a485dac" diff --git a/Content/ProjConsole/MyLib.1.fsproj b/Content/ProjConsole/MyLib.1.fsproj new file mode 100644 index 00000000..6a7fd8ce --- /dev/null +++ b/Content/ProjConsole/MyLib.1.fsproj @@ -0,0 +1,14 @@ + + + + Exe + net6.0 + + + + + + + + + diff --git a/Content/ProjConsole/Program.fs b/Content/ProjConsole/Program.fs new file mode 100644 index 00000000..d6818aba --- /dev/null +++ b/Content/ProjConsole/Program.fs @@ -0,0 +1,2 @@ +// For more information see https://aka.ms/fsharp-console-apps +printfn "Hello from F#" diff --git a/Content/ProjConsole/paket.references b/Content/ProjConsole/paket.references new file mode 100644 index 00000000..562e8c04 --- /dev/null +++ b/Content/ProjConsole/paket.references @@ -0,0 +1,2 @@ +FSharp.Core + diff --git a/Content/ProjLib/AssemblyInfo.fs b/Content/ProjLib/AssemblyInfo.fs new file mode 100644 index 00000000..6f273302 --- /dev/null +++ b/Content/ProjLib/AssemblyInfo.fs @@ -0,0 +1,23 @@ +// Auto-Generated by FAKE; do not edit +namespace System +open System.Reflection + +[] +[] +[] +[] +[] +[] +[] +[] +do () + +module internal AssemblyVersionInformation = + let [] AssemblyTitle = "MyLib.1" + let [] AssemblyProduct = "MyLib.1" + let [] AssemblyVersion = "0.1.0" + let [] AssemblyMetadata_ReleaseDate = "2017-03-17T00:00:00.0000000" + let [] AssemblyFileVersion = "0.1.0" + let [] AssemblyInformationalVersion = "0.1.0" + let [] AssemblyMetadata_ReleaseChannel = "release" + let [] AssemblyMetadata_GitHash = "bb8964b54bee133e9af64d316dc2cfee16df7f72" diff --git a/Content/ProjLib/Library.fs b/Content/ProjLib/Library.fs new file mode 100644 index 00000000..1c7f8860 --- /dev/null +++ b/Content/ProjLib/Library.fs @@ -0,0 +1,56 @@ +namespace MyLib._1 + +open System +open System.Security.Cryptography +open System.Text + +/// Initial module +module Say = + + /// Finite list of Colors + type FavoriteColor = + | Red + | Yellow + | Blue + + /// A person with many different field types + type Person = { + Name: string + FavoriteNumber: int + FavoriteColor: FavoriteColor + DateOfBirth: DateTimeOffset + } + + /// Says hello to a specific person + let helloPerson (person: Person) = + sprintf + "Hello %s. You were born on %s and your favorite number is %d. You like %A." + person.Name + (person.DateOfBirth.ToString("yyyy/MM/dd", Globalization.CultureInfo.InvariantCulture)) + person.FavoriteNumber + person.FavoriteColor + + /// + /// Adds two integers and and returns the result. + /// + /// + /// + /// This usually contains some really important information that you'll miss if you don't read the docs. + /// + /// + /// An integer. + /// An integer. + /// + /// + /// The sum of two integers. + /// + /// + /// Thrown when one parameter is max + /// and the other is greater than 0. + let add a b = a + b + + + /// I do nothing + let nothing name = + name + |> ignore diff --git a/Content/ProjLib/MyLib.1.fsproj b/Content/ProjLib/MyLib.1.fsproj new file mode 100644 index 00000000..d8934799 --- /dev/null +++ b/Content/ProjLib/MyLib.1.fsproj @@ -0,0 +1,22 @@ + + + + net6.0 + + + MyLib.1 + MyLib.1 does the thing! + + + + true + true + + + + + + + + + \ No newline at end of file diff --git a/Content/ProjLib/paket.references b/Content/ProjLib/paket.references new file mode 100644 index 00000000..073185b2 --- /dev/null +++ b/Content/ProjLib/paket.references @@ -0,0 +1,3 @@ +FSharp.Core +Microsoft.SourceLink.GitHub + diff --git a/Content/ProjTest/Main.fs b/Content/ProjTest/Main.fs new file mode 100644 index 00000000..1799d726 --- /dev/null +++ b/Content/ProjTest/Main.fs @@ -0,0 +1,9 @@ +namespace MyLib._1 + +module ExpectoTemplate = + + open Expecto + + [] + let main argv = + Tests.runTestsInAssembly defaultConfig argv diff --git a/Content/ProjTest/MyLib.1.fsproj b/Content/ProjTest/MyLib.1.fsproj new file mode 100644 index 00000000..0e5eb6b9 --- /dev/null +++ b/Content/ProjTest/MyLib.1.fsproj @@ -0,0 +1,14 @@ + + + + Exe + net6.0 + false + + + + + + + + diff --git a/Content/ProjTest/Tests.fs b/Content/ProjTest/Tests.fs new file mode 100644 index 00000000..f7cec20a --- /dev/null +++ b/Content/ProjTest/Tests.fs @@ -0,0 +1,15 @@ +namespace MyLib._1 + +open System +open Expecto + + +module SayTests = + [] + let tests = + testList "samples" [ + testCase "Add two integers" + <| fun _ -> + let result = 2 + 2 + Expect.equal result 4 "Addition works" + ] diff --git a/Content/ProjTest/paket.references b/Content/ProjTest/paket.references new file mode 100644 index 00000000..e0656287 --- /dev/null +++ b/Content/ProjTest/paket.references @@ -0,0 +1,5 @@ +Expecto +FSharp.Core +Microsoft.NET.Test.Sdk +YoloDev.Expecto.TestSdk +altcover diff --git a/Content/paket.dependencies b/Content/paket.dependencies new file mode 100644 index 00000000..dd5b5241 --- /dev/null +++ b/Content/paket.dependencies @@ -0,0 +1,2 @@ +# only here to stop paket from looking deeper into this folder +# https://github.com/fsprojects/Paket/issues/3444 diff --git a/build/Changelog.fs b/build/Changelog.fs index bea9e0d3..2efcb0a3 100644 --- a/build/Changelog.fs +++ b/build/Changelog.fs @@ -27,7 +27,11 @@ let failOnEmptyChangelog (latestEntry: Changelog.ChangelogEntry) = failwith "No changes in CHANGELOG. Please add your changes under a heading specified in https://keepachangelog.com/" -let mkLinkReference (newVersion: SemVerInfo) (changelog: Changelog.Changelog) gitHubRepoUrl = +let mkLinkReference + (newVersion: SemVerInfo) + (changelog: Changelog.Changelog) + (gitHubRepoUrl: string) + = if changelog.Entries |> List.isEmpty @@ -36,7 +40,7 @@ let mkLinkReference (newVersion: SemVerInfo) (changelog: Changelog.Changelog) gi sprintf "[%s]: %s/releases/tag/%s" newVersion.AsString - gitHubRepoUrl + (gitHubRepoUrl.TrimEnd('/')) (tagFromVersionNumber newVersion.AsString) else let versionTuple version = diff --git a/build/build.fs b/build/build.fs index f5fa5add..aee48a12 100644 --- a/build/build.fs +++ b/build/build.fs @@ -88,7 +88,7 @@ let watchDocsDir = let gitOwner = "TheAngryByrd" let gitRepoName = "MiniScaffold" -let gitHubRepoUrl = sprintf "https://github.com/%s/%s" gitOwner gitRepoName +let gitHubRepoUrl = sprintf "https://github.com/%s/%s/" gitOwner gitRepoName let documentationRootUrl = "https://www.jimmybyrd.me/MiniScaffold/" @@ -158,7 +158,7 @@ let failOnBadExitAndPrint (p: ProcessResult) = let isCI = lazy environVarAsBoolOrDefault "CI" false -// CI Servers can have bizzare failures that have nothing to do with your code +// CI Servers can have bizarre failures that have nothing to do with your code let rec retryIfInCI times fn = match isCI.Value with | true -> @@ -188,8 +188,6 @@ module dotnet = DotNet.exec optionConfig (sprintf "%s" command) args |> failOnBadExitAndPrint - let fcswatch optionConfig args = tool optionConfig "fcswatch" args - let fantomas args = DotNet.exec id "fantomas" args module DocsTool = @@ -363,6 +361,8 @@ let integrationTests ctx = // sprintf "-C %A" (configuration (ctx.Context.AllExecutingTargets)) sprintf "--project %s" proj "--summary" + if isCI.Value then + "--fail-on-focused-tests" ] |> String.concat " " diff --git a/docsSrc/Explanations/0-toc.md b/docsSrc/Explanations/0-toc.md new file mode 100644 index 00000000..6666ecd3 --- /dev/null +++ b/docsSrc/Explanations/0-toc.md @@ -0,0 +1,10 @@ +--- +title: Table of Contents +category: Explanations +categoryindex: 3 +index: 1 +--- + + +# Explanations Table of Contents + diff --git a/docsSrc/Explanations/index.md b/docsSrc/Explanations/index.md deleted file mode 100644 index 0037f49c..00000000 --- a/docsSrc/Explanations/index.md +++ /dev/null @@ -1 +0,0 @@ -# Explanations diff --git a/docsSrc/How_Tos/0-toc.md b/docsSrc/How_Tos/0-toc.md new file mode 100644 index 00000000..85a49129 --- /dev/null +++ b/docsSrc/How_Tos/0-toc.md @@ -0,0 +1,13 @@ +--- +title: Table of Contents +category: How To Guides +categoryindex: 1 +index: 1 +--- + + +# How To Guides Table of Contents + +- [Add a library project](./add-a-library-project.md) +- [Add a console project](./add-a-console-project.md) +- [Add a testing project](./add-a-testing-project.md) diff --git a/docsSrc/How_Tos/add-a-console-project.md b/docsSrc/How_Tos/add-a-console-project.md new file mode 100644 index 00000000..5048ac08 --- /dev/null +++ b/docsSrc/How_Tos/add-a-console-project.md @@ -0,0 +1,26 @@ +--- +title: Adding a console project +category: How To Guides +categoryindex: 1 +index: 100 +--- + +# Adding a Console Project + +This tutorial will show you how to add a library to your solution. We will be using the `projConsole` argument to create a library called `MyNewConsoleApp`. This template assumes you've already created a solution using the [Tutorial](../Tutorials/Getting_Started_With_Libraries.md). + +## Steps + +1. Open a terminal and navigate to the `src/` directory of your project: + - `cd src/` +2. Run `dotnet new` to create a new library project. + `dotnet new mini-scaffold -n MyNewConsoleApp --outputType projConsole` +3. Navigate back to thr root of the repository and add the project to the solution file. + - `cd ..` + - `dotnet sln add src/MyNewConsoleApp/MyNewConsoleApp.fsproj` + +## Further Reading + +- To see adding a corresponding test project see [Adding a testing project](add-a-testing-project.md). +- To see adding a corresponding library project see [Adding a library project](add-a-library-project.md). +- [NET application publishing overview](https://learn.microsoft.com/en-us/dotnet/core/deploying/) diff --git a/docsSrc/How_Tos/add-a-library-project.md b/docsSrc/How_Tos/add-a-library-project.md new file mode 100644 index 00000000..ea73e61b --- /dev/null +++ b/docsSrc/How_Tos/add-a-library-project.md @@ -0,0 +1,27 @@ +--- +title: Adding a library project +category: How To Guides +categoryindex: 1 +index: 100 +--- + +# Adding a library + +This tutorial will show you how to add a library to your solution. We will be using the `projLib` argument to create a library called `MyNewLibrary`. This template assumes you've already created a solution using the [Tutorial](../Tutorials/Getting_Started_With_Libraries.md). + +## Steps + +1. Open a terminal and navigate to the `src/` directory of your project: + - `cd src/` +2. Run `dotnet new` to create a new library project. + `dotnet new mini-scaffold -n MyNewLibrary --outputType projLib` +3. Navigate back to thr root of the repository and add the project to the solution file. + - `cd ..` + - `dotnet sln add src/MyNewLibrary/MyNewLibrary.fsproj` + +## Further Reading + +- To see adding a corresponding test project see [Adding a testing project](add-a-testing-project.md). +- To see adding a corresponding console project see [Adding a console project](add-a-console-project.md). +- [Microsoft.NET class libraries](https://learn.microsoft.com/en-us/dotnet/standard/class-libraries) +- [F# component design guidelines](https://learn.microsoft.com/en-us/dotnet/fsharp/style-guide/component-design-guidelines) diff --git a/docsSrc/How_Tos/add-a-testing-project.md b/docsSrc/How_Tos/add-a-testing-project.md new file mode 100644 index 00000000..5e3a8df1 --- /dev/null +++ b/docsSrc/How_Tos/add-a-testing-project.md @@ -0,0 +1,30 @@ +--- +title: Adding a testing project +category: How To Guides +categoryindex: 1 +index: 300 +--- + +# Adding a Testing project + +This tutorial will show you how to add a test project to your solution. We will be using the `projTest` argument to create a project called `MyNewLibrary.Tests`. This template assumes you've already created a solution using the [Tutorial](../Tutorials/Getting_Started_With_Libraries.md). + +## Steps + +1. Open a terminal and navigate to the `tests/` directory of your project: + - `cd tests/` +2. Run `dotnet new` to create a new library project. + `dotnet new mini-scaffold -n MyNewLibrary.Tests --outputType projLib` +3. Navigate back to thr root of the repository and add the project to the solution file. + - `cd ..` + - `dotnet sln add src/MyNewLibrary.Tests/MyNewLibrary.Tests.fsproj` +4. Optionally, add a reference to the project you want to test. + - `dotnet add src/MyNewLibrary.Tests/MyNewLibrary.Tests.fsproj reference src/MyNewLibrary/MyNewLibrary.fsproj` + +## Further Reading + +- To see adding a corresponding library project see [Adding a testing project](add-a-library-project.md). +- To see adding a corresponding console project see [Adding a console project](add-a-console-project.md). +- MiniScaffold uses [Expecto](https://github.com/haf/expecto) for testing. See the [Expecto documentation](https://github.com/haf/expecto#testing-hello-world). +- [Unit testing best practices with .NET Core and .NET Standard](https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices) + diff --git a/docsSrc/How_Tos/index.md b/docsSrc/How_Tos/index.md deleted file mode 100644 index 785e921b..00000000 --- a/docsSrc/How_Tos/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# How Tos - - diff --git a/docsSrc/Reference/0-toc.md b/docsSrc/Reference/0-toc.md new file mode 100644 index 00000000..0d24746b --- /dev/null +++ b/docsSrc/Reference/0-toc.md @@ -0,0 +1,11 @@ +--- +title: Table of Contents +category: Reference +categoryindex: 4 +index: 0 +--- + + +# Tutorials Table of Contents +- [Library Scaffold output file explanations](Library_Output.html) + diff --git a/docsSrc/Reference/index.md b/docsSrc/Reference/index.md deleted file mode 100644 index 196a7c98..00000000 --- a/docsSrc/Reference/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Reference - -- [Library Scaffold output file explanations](Library_Output.html) -- Console Scaffold output file explanations diff --git a/docsSrc/Tutorials/0-toc.md b/docsSrc/Tutorials/0-toc.md new file mode 100644 index 00000000..656562de --- /dev/null +++ b/docsSrc/Tutorials/0-toc.md @@ -0,0 +1,11 @@ +--- +title: Table of Contents +category: Tutorials +categoryindex: 0 +index: 0 +--- + + +# Tutorials Table of Contents + +- [Get Started with a Library solution](Getting_Started_With_Libraries.md) diff --git a/docsSrc/Tutorials/Getting_Started_With_Libraries.md b/docsSrc/Tutorials/Getting_Started_With_Libraries.md index 2c570798..84d0711a 100644 --- a/docsSrc/Tutorials/Getting_Started_With_Libraries.md +++ b/docsSrc/Tutorials/Getting_Started_With_Libraries.md @@ -1,13 +1,18 @@ +--- +title: Get Started with a Library solution +category: Tutorials +categoryindex: 0 +index: 100 +--- + # Getting Started -In this tutorial, we'll take a look at getting started with MiniScaffold and publishing your first library to NuGet and GitHub +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](https://git-scm.com/download) - Install [.Net core](https://dotnet.microsoft.com/download) -- If on macOS or Linux, install [Mono](https://www.mono-project.com/download/stable/) -- If on Windows [ensure](https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed) you have at least .NET Full Framework 4.6.1 installed - Recommended IDE is [VSCode with Ionide](https://docs.microsoft.com/en-us/dotnet/fsharp/get-started/install-fsharp#install-f-with-visual-studio-code) - Create a [NuGet account](https://www.nuget.org/) - Create a [GitHub account](https://github.com/) @@ -31,10 +36,12 @@ This will generate a structure similar to this . ├── CHANGELOG.md ├── Directory.Build.props + ├── Directory.Build.targets ├── LICENSE.md - ├── MyLib.1.sln ├── README.md ├── build + │   ├── Changelog.fs + │   ├── FsDocs.fs │   ├── build.fs │   ├── build.fsproj │   └── paket.references @@ -48,52 +55,34 @@ This will generate a structure similar to this │   │   └── Doing_Another_Thing.md │   ├── Tutorials │   │   └── Getting_Started.md + │   ├── _menu-item_template.html + │   ├── _menu_template.html + │   ├── _template.html │   ├── 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 + │   │   ├── fsdocs-custom.css + │   │   ├── fsdocs-dark.css + │   │   ├── fsdocs-light.css + │   │   ├── fsdocs-main.css + │   │   ├── navbar-fixed-left.css + │   │   └── theme-toggle.js │   └── 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 + ├── MyCoolNewLib.sln ├── paket.dependencies ├── paket.lock ├── src │   ├── Directory.Build.props - │   └── MyLib.1 + │   └── MyCoolNewLib │   ├── AssemblyInfo.fs │   ├── Library.fs - │   ├── MyLib.1.fsproj + │   ├── MyCoolNewLib.fsproj │   └── paket.references └── tests ├── Directory.Build.props - └── MyLib.1.Tests - ├── AssemblyInfo.fs + └── MyCoolNewLib.Tests ├── Main.fs - ├── MyLib.1.Tests.fsproj ├── Tests.fs + ├── MyCoolNewLib.Tests.fsproj └── 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. @@ -138,48 +127,57 @@ If it does not complete successfully, either [open an issue](https://github.com/ ## Fill out README.md -The README.md comes with a lot of information but it's recommended to fill out the introductionary description. +The README.md comes with a lot of information but it's recommended to fill out the introduction 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. +The release process is streamlined so you only have to start your git repository, set your NuGet keys for GitHub Actions, create `CHANGELOG` notes, and run the `Release` build target. After you've done the initial setup, you will only need to perform the last two steps for each release. + +### Create your Github Repository - [Create a GitHub Repository](https://help.github.com/en/github/getting-started-with-github/create-a-repo) and [Start a git repo with your GitHub repository as a remote](https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/) - [lang=bash] + git init git add . git commit -m "Scaffold" git remote add origin https://github.com/MyGithubUsername/MyCoolNewLib.git git push -u origin master + ``` + +### Add your NUGET_TOKEN to your environment -- [Create a NuGet API key](https://docs.microsoft.com/en-us/nuget/nuget-org/publish-a-package#create-api-keys) +- Our NuGet package is created with a [GitHub Action](https://github.com/features/actions) This action needs to be able to push to NuGet. To do this, we need to add our NuGet API key to our GitHub repository's secrets. +- [Create an Environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#creating-an-environment) on your repository named `nuget`. +- [Create a NuGet API key](https://learn.microsoft.com/en-us/nuget/nuget-org/publish-a-package#create-an-api-key) +- Add your `NUGET_TOKEN` to the [Environment Secrets](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-secrets) of your newly created environment. - - [Add your NuGet API key to paket](https://fsprojects.github.io/Paket/paket-config.html#Adding-a-NuGet-API-key) - - or set the environment variable `NUGET_TOKEN` to your key -- [Create a GitHub OAuth Token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) - - You can then set the `GITHUB_TOKEN` to upload `CHANGELOG` notes and artifacts to github - - If you're on a linux, you can put this key into your [.bashrc](https://unix.stackexchange.com/questions/129143/what-is-the-purpose-of-bashrc-and-how-does-it-work) - - Otherwise it will fallback to username/password +### Prepare your CHANGELOG.md Then update the `CHANGELOG.md` with an "Unreleased" section containing release notes for this version, in [KeepAChangelog](https://keepachangelog.com/en/1.1.0/) format. -Here's an example of adding an "Unreleased" section to a `CHANGELOG.md` with a `0.1.0` section already released. +Here's an example of adding an `Unreleased` section to a `CHANGELOG.md` with a `0.1.0` section already released. + [lang=markdown] ## [Unreleased] ### Added - - Does cool stuff! (https://github.com/MyGithubUsername/MyCoolNewLib/pull/001) + - Does cool stuff! (https://github.com/MyGithubUsername/MyCoolNewLib/pull/001) (Thanks @TheAngryByrd!) ### Fixed - - Fixes that silly oversight (https://github.com/MyGithubUsername/MyCoolNewLib/pull/002) + - Fixes that silly oversight (https://github.com/MyGithubUsername/MyCoolNewLib/pull/002) (Thanks! @baronfel) ## [0.1.0] - 2017-03-17 First release @@ -191,12 +189,16 @@ Here's an example of adding an "Unreleased" section to a `CHANGELOG.md` with a ` [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: + variable, or else as a parameter after the target name. + - `./build.sh Release 0.2.0` + +- This target will do the following for you: - 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 +- The GitHub Action will then: + - publish the package to NuGet - create a GitHub release for that git tag macOS/Linux Parameter: diff --git a/docsSrc/Tutorials/index.md b/docsSrc/Tutorials/index.md deleted file mode 100644 index 513ed92b..00000000 --- a/docsSrc/Tutorials/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tutorials - -- [Getting Started with Libraries](Getting_Started_With_Libraries.html) diff --git a/docsSrc/index.md b/docsSrc/index.md index e4764e19..c7c041e7 100644 --- a/docsSrc/index.md +++ b/docsSrc/index.md @@ -94,7 +94,7 @@ This takes away the ambiguity that developers face when creating an OSS project.

Takes you by the hand through a series of steps to create your first library.

- Get started + Get started
@@ -105,7 +105,7 @@ This takes away the ambiguity that developers face when creating an OSS project.

Guides you through the steps involved in addressing key problems and use-cases.

- Learn Usecases + Learn Usecases
@@ -116,7 +116,7 @@ This takes away the ambiguity that developers face when creating an OSS project.

Discusses key topics and concepts at a fairly high level and provide useful background information and explanation..

- Dive Deeper + Dive Deeper
@@ -127,7 +127,7 @@ This takes away the ambiguity that developers face when creating an OSS project.

Contain technical references.

- Read References + Read References
diff --git a/tests/MiniScaffold.Tests/Asserts.fs b/tests/MiniScaffold.Tests/Asserts.fs index 9eeca7ec..12d7600f 100644 --- a/tests/MiniScaffold.Tests/Asserts.fs +++ b/tests/MiniScaffold.Tests/Asserts.fs @@ -132,10 +132,65 @@ module Assert = let ``README exists`` = tryFindFile "README.md" + let ``File exists`` path = tryFindFile path + module Effect = open System open Fake.IO open Fake.Tools + open Fake.Core + open Fake.DotNet + open Infrastructure.Dotnet + + let ``dotnet run`` argStr projectPath (d: DirectoryInfo) = + + DotNet.exec + (fun opt -> { + opt with + WorkingDirectory = Path.Join(d.FullName, projectPath) + }) + "run" + argStr + |> failOnBadExitAndPrint + + let ``dotnet new`` argsStr (path: string) (d: DirectoryInfo) = + + DotNet.exec + (fun opt -> { + opt with + WorkingDirectory = Path.Join(d.FullName, path) + }) + "new" + argsStr + |> failOnBadExitAndPrint + + let ``dotnet add reference`` args path (d: DirectoryInfo) = + let args = + Arguments.Empty + |> Arguments.appendNotEmpty "reference" args + + DotNet.exec + (fun opt -> { + opt with + WorkingDirectory = Path.Join(d.FullName, path) + }) + "add" + args.ToStartInfo + |> failOnBadExitAndPrint + + let ``dotnet sln add`` argsStr (d: DirectoryInfo) = + let args = + Arguments.Empty + |> Arguments.appendNotEmpty "add" argsStr + + DotNet.exec + (fun opt -> { + opt with + WorkingDirectory = d.FullName + }) + "sln" + args.ToStartInfo + |> failOnBadExitAndPrint let ``format build`` (d: DirectoryInfo) = Dotnet.fantomas d.FullName "build" diff --git a/tests/MiniScaffold.Tests/Infrastructure.fs b/tests/MiniScaffold.Tests/Infrastructure.fs index e2ab8bce..cf489172 100644 --- a/tests/MiniScaffold.Tests/Infrastructure.fs +++ b/tests/MiniScaffold.Tests/Infrastructure.fs @@ -35,18 +35,15 @@ module Dotnet = let install name = let args = Arguments.Empty - |> Arguments.appendNotEmpty "-i" name - // |> Arguments.appendRaw "--dev:install" - // |> - // let args = [ - // sprintf "-i \"%s\"" name - // ] + |> Arguments.appendNotEmpty "install" name + |> Arguments.appendRaw "--force" + cmd id args.ToStartInfo let uninstall name = let args = Arguments.Empty - |> Arguments.appendNotEmpty "-u" name + |> Arguments.appendNotEmpty "uninstall" name cmd id args.ToStartInfo diff --git a/tests/MiniScaffold.Tests/Tests.fs b/tests/MiniScaffold.Tests/Tests.fs index 5d60f177..cf5eb96c 100755 --- a/tests/MiniScaffold.Tests/Tests.fs +++ b/tests/MiniScaffold.Tests/Tests.fs @@ -119,8 +119,8 @@ module Tests = [] let tests = - testSequenced - <| // uncomment to get better logs + // testSequenced + // <| // uncomment to get better logs testList "samples" [ do setup () yield! @@ -130,8 +130,58 @@ module Tests = [ yield! projectStructureAsserts Assert.``project can build target`` "DotnetPack" - // Assert.``project can build target`` "BuildDocs" + Assert.``project can build target`` "BuildDocs" ] + + + testCase, + "-n ProjLibTest --githubUsername CoolPersonNo0", + [ + yield! projectStructureAsserts + Assert.``project can build target`` "DotnetPack" + Effect.``dotnet new`` + "mini-scaffold -n MyCoolLib3 --githubUsername CoolPersonNo3 --outputType projLib" + "src" + Effect.``dotnet sln add`` "src/MyCoolLib3/MyCoolLib3.fsproj" + Assert.``File exists`` "src/MyCoolLib3/MyCoolLib3.fsproj" + Assert.``project can build target`` "DotnetPack" + ] + + testCase, + "-n ProjConsoleTest --githubUsername CoolPersonNo0", + [ + yield! projectStructureAsserts + Assert.``project can build target`` "DotnetPack" + Effect.``dotnet new`` + "mini-scaffold -n MyCoolConsole --githubUsername CoolPersonNo3 --outputType projConsole" + "src" + Effect.``dotnet sln add`` "src/MyCoolConsole/MyCoolConsole.fsproj" + Assert.``File exists`` "src/MyCoolConsole/MyCoolConsole.fsproj" + Assert.``project can build target`` "DotnetPack" + Effect.``dotnet run`` "" "src/MyCoolConsole/" + ] + + + testCase, + "-n ProjTestTest --githubUsername CoolPersonNo0", + [ + yield! projectStructureAsserts + Assert.``project can build target`` "DotnetPack" + Effect.``dotnet new`` + "mini-scaffold -n MyCoolLib3 --githubUsername CoolPersonNo3 --outputType projLib" + "src" + Effect.``dotnet sln add`` "src/MyCoolLib3/MyCoolLib3.fsproj" + Effect.``dotnet new`` + "mini-scaffold -n MyCoolLib3.Tests --githubUsername CoolPersonNo3 --outputType projTest" + "tests" + Effect.``dotnet sln add`` "tests/MyCoolLib3.Tests/MyCoolLib3.Tests.fsproj" + Effect.``dotnet add reference`` + "../../src/MyCoolLib3/MyCoolLib3.fsproj" + "tests/MyCoolLib3.Tests/" + Assert.``File exists`` "tests/MyCoolLib3.Tests/MyCoolLib3.Tests.fsproj" + Assert.``project can build target`` "DotnetPack" + ] + // test for dashes in name https://github.com/dotnet/templating/issues/1168#issuecomment-364592031 testCase, "-n fsharp-data-sample --githubUsername CoolPersonNo2", @@ -219,14 +269,6 @@ module Tests = Effect.``make build function fail`` "let dotnetPack" Assert.``build target with failure expected`` "Publish" ] - ptestCase - "SourceLinkTests aren't working since the testing tool is very out of date", - "-n SourceLinkTestFail --githubUsername TestAccount", - [ - Effect.``setup for publish tests`` - Effect.``make build function fail`` "let sourceLinkTest" - Assert.``build target with failure expected`` "Publish" - ] testCase, "-n PublishToNugetFail --githubUsername TestAccount",