Merge pull request #2081 from fsharp/release/next

Release 5.6.1

RELEASE_NOTES.md

@@ -1,5 +1,11 @@
 # Release Notes
 
+## 5.6.1 - 2018-09-09
+
+* BUGFIX: dotnet restore with configfile did not work - https://github.com/fsharp/FAKE/issues/2082
+* BUGFIX: Fake cache was broken - https://github.com/fsharp/FAKE/issues/2083
+* DOCS: various improvements in the documentation - https://github.com/fsharp/FAKE/pull/2081
+
 ## 5.6.0 - 2018-09-09
 
 * NEW: Fake.DotNet.Testing.DotCover module - https://github.com/fsharp/FAKE/pull/2058

build.fsx

@@ -95,16 +95,10 @@ let legacyDir = srcDir</>"legacy"
 
 let nuget_exe = Directory.GetCurrentDirectory() </> "packages" </> "build" </> "NuGet.CommandLine" </> "tools" </> "NuGet.exe"
 
-// until bugfix in Vault.fs is released
-#load "src/app/Fake.Core.Vault/Vault.fs"
-
-let vault = Vault.fromFakeEnvironmentVariable()
-    (*
-    let envVar = "FAKE_VAULT_VARIABLES"
-    let vars = Environment.environVarOrDefault envVar ""
-    if System.String.IsNullOrEmpty vars then
-        TeamFoundation.variables
-    else Vault.fromEnvironmentVariable envVar*)
+let vault =
+    match Vault.fromFakeEnvironmentOrNone() with
+    | Some v -> v
+    | None -> TeamFoundation.variables
 
 let getVarOrDefault name def =
     match vault.TryGet name with
@@ -166,26 +160,6 @@ let chocoVersion =
 
 Trace.setBuildNumber nugetVersion
 
-// TODO: Get rid of me
-let private publishTests runnerType (resultsFiles:string seq) (mergeResults:bool) (platform:string) (config:string) (runTitle:string) (publishRunAttachments:bool) =
-    TeamFoundation.write "results.publish"
-        [ yield "type", runnerType
-          if mergeResults then
-            yield "mergeResults", "true"
-          if String.isNotNullOrEmpty platform then
-            yield "platform", platform
-          if String.isNotNullOrEmpty config then
-            yield "config", config
-          if String.isNotNullOrEmpty runTitle then
-            yield "runTitle", runTitle
-          if publishRunAttachments then
-            yield "publishRunAttachments", "true"
-          if not (Seq.isEmpty resultsFiles) then
-            yield "resultFiles", System.String.Join(",", resultsFiles |> Seq.map Path.GetFullPath)
-          yield "testRunSystem", "VSTSTask" ]
-        ""
-
-
 let dotnetSdk = lazy DotNet.install DotNet.Versions.Release_2_1_302
 let inline dtntWorkDir wd =
     DotNet.Options.lift dotnetSdk.Value
@@ -569,16 +543,14 @@ Target.create "DotNetCoreIntegrationTests" (fun _ ->
     let processResult =
         DotNet.exec (dtntWorkDir root) "src/test/Fake.Core.IntegrationTests/bin/Release/netcoreapp2.1/Fake.Core.IntegrationTests.dll" "--summary"
     if processResult.ExitCode <> 0 then failwithf "DotNet Core Integration tests failed."
-    //Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_IntegrationTests.TestResults.xml"
-    publishTests "NUnit" ["Fake_Core_IntegrationTests.TestResults.xml"] false "" "" "" true
+    Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_IntegrationTests.TestResults.xml"
 )
 
 Target.create "TemplateIntegrationTests" (fun _ ->
     let processResult =
         DotNet.exec (dtntWorkDir (srcDir </> "test" </> "Fake.DotNet.Cli.IntegrationTests")) "bin/Release/netcoreapp2.1/Fake.DotNet.Cli.IntegrationTests.dll" "--summary"
     if processResult.ExitCode <> 0 then failwithf "DotNet CLI Template Integration tests failed."
-    //Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_DotNet_Cli_IntegrationTests.TestResults.xml"
-    publishTests "NUnit" ["Fake_DotNet_Cli_IntegrationTests.TestResults.xml"] false "" "" "" true
+    Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_DotNet_Cli_IntegrationTests.TestResults.xml"
 )
 
 Target.create "DotNetCoreUnitTests" (fun _ ->
@@ -587,16 +559,14 @@ Target.create "DotNetCoreUnitTests" (fun _ ->
         DotNet.exec (dtntWorkDir root) "src/test/Fake.Core.UnitTests/bin/Release/netcoreapp2.1/Fake.Core.UnitTests.dll" "--summary"
 
     if processResult.ExitCode <> 0 then failwithf "Unit-Tests failed."
-    //Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_UnitTests.TestResults.xml"
-    publishTests "NUnit" ["Fake_Core_UnitTests.TestResults.xml"] false "" "" "" true
+    Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_UnitTests.TestResults.xml"
 
     // dotnet run --project src/test/Fake.Core.CommandLine.UnitTests/Fake.Core.CommandLine.UnitTests.fsproj
     let processResult =
         DotNet.exec (dtntWorkDir root) "src/test/Fake.Core.CommandLine.UnitTests/bin/Release/netcoreapp2.1/Fake.Core.CommandLine.UnitTests.dll" "--summary"
 
     if processResult.ExitCode <> 0 then failwithf "Unit-Tests for Fake.Core.CommandLine failed."
-    //Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_CommandLine_UnitTests.TestResults.xml"
-    publishTests "NUnit" ["Fake_Core_CommandLine_UnitTests.TestResults.xml"] false "" "" "" true
+    Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_CommandLine_UnitTests.TestResults.xml"
 )
 
 Target.create "BootstrapTestDotNetCore" (fun _ ->
@@ -610,7 +580,6 @@ Target.create "BootstrapTestDotNetCore" (fun _ ->
             [ ".fake/testbuild.fsx/packages"
               ".fake/testbuild.fsx/paket.depedencies.sha1"
               ".fake/testbuild.fsx/paket.lock"
-              ".fake/testbuild.fsx/assemblies.cached"
               "testbuild.fsx.lock" ]
             |> List.iter Shell.rm_rf
             // TODO: Clean a potentially cached dll as well.

help/markdown/buildserver.md

@@ -38,7 +38,7 @@ CoreTracing.ensureConsoleListener ()
 Target.create "Test" (fun _ ->
     File.WriteAllText("myfile.txt", "some content")
 
-    // traceTag can be used to open scopes/blocks. They will be shown in the build-server visualization supported.
+    // traceTag can be used to open scopes/blocks. They will be shown in the build-server visualization if supported.
     ( use testsuite = Trace.traceTag (KnownTags.TestSuite "some-testsuite") "Starting unit test"
       ( use _ = Trace.traceTag (KnownTags.Test "some-test") "Starting unit test 1"
         // Scope of the test
@@ -50,6 +50,11 @@ Target.create "Test" (fun _ ->
     // Uploads an artifact no matter the build-server
     Trace.publish ImportData.BuildArtifact "myfile.txt"
 
+    // Uploads test results no matter the build-server
+    // Note: There might be limitations on some system with some imports.
+    // Please help by testing, submitting issues and pull requests.
+    Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_CommandLine_UnitTests.TestResults.xml"
+
     Trace.setBuildNumber "my-build-number"
 
     Trace.traceImportant "tries to write in yellow"
@@ -64,3 +69,19 @@ Target.create "Test" (fun _ ->
 ## Implementing support for a build-server
 
 Please look at the existing implementations. Please contribute new implementations to the repository. Some changes like adding new cases to the `TraceListener` module are not considered breaking changes. Using these types (using `match` on these types to be exact) outside the fake repository is not considered good practice.
+
+## Example FAKE repository
+
+Fake itself uses AppVeyor and TeamFoundation support for importing and displaying test results:
+
+```fsharp
+// import test result
+Trace.publish (ImportData.Nunit NunitDataVersion.Nunit) "Fake_Core_CommandLine_UnitTests.TestResults.xml"
+
+// upload artifacts
+Trace.publish ImportData.BuildArtifact ("release/dotnetcore/fake-dotnetcore-win7-x64.zip")
+```
+
+Look at this [CI-build](https://fakebuild.visualstudio.com/FSProjects/FSProjects%20Team/_build/results?buildId=425) for an example on how it looks in VSTS.
+
+![AppVeyor test import](/pics/buildserver/AppVeyor_imported_tests.png)

help/markdown/contributing.md

@@ -132,7 +132,7 @@ e.g: Using dotnet cli
 
     e.g: If you wanted to test a local build of Fake.DotNet.NuGet
 
-        #r "paket: 
+        #r "paket:
         source path/to/Fake.DotNet.NuGet/bin/Debug/
         source https://api.nuget.org/v3/index.json
         ...Other Dependencies...
@@ -156,6 +156,8 @@ If you ever need a release/bugfix fast, make sure to mention that in your PR, we
      Those bits should be considered for "unblocking"-purposes or testing only.
 </div>
 
+The [release process](https://fakebuild.visualstudio.com/FSProjects/_releases2?definitionId=1&view=mine&_a=releases) is publicly available as well.
+
 ## General considerations
 
 * Fake 4 (FakeLib) is in maintainance mode. Therefore new features need to be at least available as new FAKE 5 module (that might mean that the old module needs to be migrated as part of the PR).

help/markdown/fake-dotnetcore.md

@@ -78,17 +78,35 @@ See [Fake command line](fake-commandline.html)
 AppVeyor: [https://github.com/fsharp/FAKE/blob/master/appveyor.yml](https://github.com/fsharp/FAKE/blob/master/appveyor.yml)
 Travis: [https://github.com/fsharp/FAKE/blob/master/.travis.yml](https://github.com/fsharp/FAKE/blob/master/.travis.yml)
 
-## Why?
-
-The goals are:
-
-- Provide a easy to use cross platform way to use FAKE. With a good bootstrapping experience
-- Cleanup 'FakeLib'
-- Extract reusable libraries and make them usable for your projects or the fsi!
-- Make it easier to extend FAKE for your own use-case
-- Provide an easy way for simple scripting, automate everything, everywhere.
-
-Please read https://github.com/fsharp/FAKE/issues/1232
+## One note on Intellisense
+
+This section is to clarify when an how the intellisense updates when you add new modules (short form: Delete the `<script>.fsx.lock` file and re-run fake to update all files)
+
+* Assume you have a script `myscript.fsx` with the following contents:
+
+  ```fsharp
+  #r "paket:
+  nuget Fake.Core.Target prerelease"
+  #load "./.fake/myscript.fsx/intellisense.fsx"
+  ```
+
+  Where you can add all the [fake modules](fake-fake5-modules.html) you need (work through the example below if you see this the first time).
+
+* run the script to restore your dependencies and setup the intellisense support: `fake run myscript.fsx`.
+  This might take some seconds depending on your internet connection  
+<div class="alert alert-info">
+    <h5>INFO</h5>
+    <p>The warning <code>FS0988: Main module of program is empty: nothing will happen when it is run</code> indicates that you have not written any code into the script yet.</p>
+</div>
+
+* now open the script in VS Code with ionide-fsharp extension or Visual Studio.
+<div class="alert alert-info">
+    <h5>INFO</h5>
+    <p>
+    If you change your dependencies you need to delete <code>myscript.fsx.lock</code> and run the script again for intellisense to update.
+    Intellisense is shown for the full framework while the script is run as <code>netcoreapp20</code> therefore intellisense might show APIs which are not actually usable.
+    </p>
+</div>
 
 ## What is the migration path?
 

help/markdown/fake-gettingstarted.md

@@ -57,35 +57,9 @@ There are various ways to install FAKE 5:
 
 * Bootstrap via paket `clitool`, basically the same as `DotNetCliToolReference` but managed via paket. See the [`paket_clitool` branch of `fake-bootstrap`](https://github.com/FakeBuild/fake-bootstrap/tree/paket_clitool) in particular the [build.proj](https://github.com/FakeBuild/fake-bootstrap/blob/paket_clitool/build.proj) file.
 
-## Create and Edit scripts with Intellisense
+## One note on Intellisense
 
-Once `fake` is available you can start creating your script:
-
-* Create a new file `myscript.fsx` with the following contents:
-
-  ```fsharp
-  #r "paket:
-  nuget Fake.Core.Target prerelease"
-  #load "./.fake/myscript.fsx/intellisense.fsx"
-  ```
-
-  Where you can add all the [fake modules](fake-fake5-modules.html) you need.
-
-* run the script to restore your dependencies and setup the intellisense support: `fake run myscript.fsx`.
-  This might take some seconds depending on your internet connection  
-<div class="alert alert-info">
-    <h5>INFO</h5>
-    <p>The warning <code>FS0988: Main module of program is empty: nothing will happen when it is run</code> indicates that you have not written any code into the script yet.</p>
-</div>
-
-* now open the script in VS Code with ionide-fsharp extension or Visual Studio.
-<div class="alert alert-info">
-    <h5>INFO</h5>
-    <p>
-    If you change your dependencies you need to delete <code>myscript.fsx.lock</code> and run the script again for intellisense to update.
-    Intellisense is shown for the full framework while the script is run as <code>netcoreapp20</code> therefore intellisense might show APIs which are not actually usable.
-    </p>
-</div>
+Whenever you update the dependencies (part of the example) delete the `<script>.fsx.lock` file and re-run fake to update all files and intellisense!
 
 ## Example - Compiling and building your .NET application
 
@@ -104,7 +78,7 @@ nuget Fake.Core.Target //"
 
 This is all we need for now to declare that we need the `Fake.Core.Target` module and want to enable intellisense.
 
-Now run `fake run build.fsx` to make fake prepare our environment. Now our IDE can load the dependencies and will have intellisense enabled (you might need to reopen the script file on some Editors).
+Now run `fake run build.fsx` to make fake prepare our environment. Now our IDE can load the dependencies and will have intellisense enabled (you might need to reopen the script file on some editors).
 
 Now that we have setup our basic environment to edit the script file we add our first target:
 
@@ -164,7 +138,7 @@ let buildDir = "./build/"
 
 // Targets
 Target.create "Clean" (fun _ ->
-  Shell.CleanDir buildDir
+  Shell.cleanDir buildDir
 )
 
 Target.create "Default" (fun _ ->

help/markdown/fake-what-is-fake.md

@@ -1,5 +1,7 @@
 # F# Make - What is FAKE?
 
+> This a general discussion about FAKE, [here you can learn about the FAKE 5 upgrade](fake-fake5-learn-more.html) or see [how to contribute](contributing.html)
+
 [![Join the chat at https://gitter.im/fsharp/FAKE](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/fsharp/FAKE?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 "FAKE - F# Make" is a cross platform build automation system. Due to its integration 
@@ -10,3 +12,49 @@ Visual Studio or MonoDevelop, which provide syntax highlighting and code complet
 The new DSL was designed to be succinct, typed, declarative, extensible and easy to use.
 
 See the [project home page](index.html) for tutorials and [API documentation](apidocs/v5/index.html).
+
+## Why FAKE?
+
+The industry movement towards "DevOps" and "infrastructure as code" leads to the fact that reproducible builds and automation becomes more and more important for basically every project.
+Question is: Why do we build our automations in "old" and error-prone scripting languages like `bash`, `cmd` or `powershell` instead of a full featured language with IDE support, static typing and compile-time errors?
+We believe there are different answers to that:
+
+- The build/release process starts very simple, often with a single command. Setup a C# project or installing dependencies feels like overkill
+- People use/depend on external systems and deeply integrate into those.
+- Lack of awareness of other options
+
+FAKE addresses the problem in the following ways:
+
+- It builds on top of a fully featured statically typed and productive language (F#) with several IDE options.
+- It lowers the entry point by working on top of script files. No project file or dependencies besides the fake runner.
+- Remove dependencies from the CI/CD system while providing full integration. Make features available locally.
+  With FAKE you can choose and switch between multiple system easily while having almost native integrations.
+- Provide modules for the most commonly used tasks.
+- Make it easy to start external processes through various APIs.
+- Add all your automation scripts to your repository.
+
+## When should I use FAKE
+
+Use FAKE in the following ways:
+
+- Remove/reduce dependencies on your CI/CD system
+- Make automations reproducable and testable
+- Replace existing Shell-Scripts
+- Automate manual tasks
+
+Try to not use fake:
+
+- To replace msbuild
+- To replace/rewrite existing tools you currently execute as part of your build process
+
+  > Using a fake module is preferred over calling external processes directly.
+
+Examples:
+
+- [Twitter](https://twitter.com/JonathanOhlrich/status/1031591590186442753)
+- [(Video) Immutable application deployments with F# Make - Nikolay Norman Andersen](https://www.youtube.com/watch?v=_sZT0CpJ6Vo)
+- [(fake 4 API) Elasticsearch.Net](https://www.elastic.co/de/blog/solidifying-releases-with-fsharp-make)
+
+## Get started
+
+With our [quickstart](fake-dotnetcore.html) and [getting-started](fake-gettingstarted.html) guides.

help/templates/indexpage.cshtml

@@ -13,9 +13,9 @@
 								<h2><strong>F# Make 5</strong> - A DSL for build tasks and more
 								<br />
 								The power of F# - anywhere - anytime</h2>
-								<p>FAKE 5 is stable, but as a community project we always have work to do ... PLEASE HELP
+								<p>FAKE 5 is stable, as a community project we always have work to do ... PLEASE HELP
                                 </p>
-								<a href="fake-fake5-learn-more.html" class="button big icon fa-check-circle">Learn more</a>
+								<a href="fake-what-is-fake.html" class="button big icon fa-check-circle">Learn more</a>
 							</div>
 }