merged 3.1 from master

README.md

@@ -175,22 +175,69 @@ First, it starts with an "F" just like many other F# projects.
 Second, Fantomas is my favourite character in the literature.
 Finally, Fantomas has the same Greek root as "[phantom](https://en.wiktionary.org/wiki/phantom)"; coincidentally F# ASTs and formatting rules are so *mysterious* to be handled correctly.
 
-## How to contribute
-Would like to contribute? Discuss on [issues](../../issues) and send pull requests. You can get started by helping us handle ["You Take It" issues](https://github.com/dungpa/fantomas/issues?labels=You+Take+It&page=1&state=open).
+## Contributing guide
+
+Thank you for your interest in contributing to Fantomas! This guide explains everything you'll need to know to get started.
+
+### Before touching the code
+- Open an issue to propose the change you have in mind. 
+- For bugs, please create them using the [online tool](https://jindraivanek.gitlab.io/fantomas-ui/). Update the title of the issue with something meaningful instead of `Bug report from fantomas-ui`.
+- For stylistic changes, please take the time to discuss them and consider all possible outcomes of the change. Consult the [fsharp style guide](https://docs.microsoft.com/en-us/dotnet/fsharp/style-guide/) for guidance.
+New behavior should most likely be optional because a configuration flag. 
+Always keep the following train of thought: if a user upgrades Fantomas to a new version, the result of formatting with the default settings should not change.
+- For new features, the same things apply: please discuss before making a PR.  
+
+### PR checklist
+- [ ] Did you cover all new code changes with unit tests? Unit tests are extremely important for this project. 
+When we upgrade the [FSharp.Compiler.Service](https://www.nuget.org/packages/FSharp.Compiler.Service/) they are the only thing that tell us if all the existing behavior still works.
+- [ ] When writing test also consider minor variations:
+    - [ ] are `*.fsi` files impacted?
+    - [ ] does this work in nested scenarios?
+    - [ ] would strict mode enabled have an impact?
+    - [ ] multiple code paths in case of defines? (`#if DEBUG`, ...)
+
+### Conventions
+
+- Unit test names should start with a lowercase letter unless the first word is a name of any sort.
+- When creating a test that is linked to a GitHub issue, add the number at the back with a comma
+f.ex.
+```fsharp
+[<Test>]
+let ``preserve compile directive between piped functions, 512`` () = ...
+```
+
+### Tools
+
+- F# AST Viewer: https://jindraivanek.gitlab.io/ast-viewer/
+- F# Tokens: https://nojaf.github.io/fsharp-tokens/
+- Fantomas Online: https://jindraivanek.gitlab.io/fantomas-ui/
 
-To get an understanding of the code, either:
-- start by looking at contribution examples (see [Contribution examples](#contribution-examples) section below);
-- or read the few following [architectural notes](#architectural-notes) & tips to help you get started playing with the code.
+### Upgrading FSharp.Compiler.Service
+
+When upgrading the [FSharp.Compiler.Service](https://www.nuget.org/packages/FSharp.Compiler.Service/) please consider the following order:
+
+- Update [AST Viewer](https://gitlab.com/jindraivanek/ast-viewer)
+- Update [F# Tokens](https://github.com/nojaf/fsharp-tokens)
+- Update Fantomas (this repository)
+- Update [Fantomas UI preview branch](https://gitlab.com/jindraivanek/fantomas-ui/tree/preview)
+- After a release on NuGet, update [Fantomas UI master branch](https://gitlab.com/jindraivanek/fantomas-ui/tree/master)
+
+This doesn't mean that one person should do all the work ;)
 
 ### Architectural notes
 Fantomas' features are basically two commands: *format a document* or *format a selection* in the document.
 
-They both consist in the same two stages:
+They both consist of these stages:
 
-- parse the code and generate the F# AST (Abstract Syntax Tree). This is provided by the
+- determine the combinations of code paths by checking the defines found in the source code.
+- for each code path:
+    - parse the code and generate the F# AST (Abstract Syntax Tree). This is provided by the
 by the FSharp.Compiler.Services library (see the `parse` function in
 [CodeFormatterImpl.fs](src/Fantomas/CodeFormatterImpl.fs)).
-- rewrite the code based on the AST (previous step) and formatting settings.
+    - parse the code for trivia items by checking the F# tokens (`Trivia.collectTrivia`). Trivia items are additional information like newlines, comments and keywords which are not part of the F# AST. 
+    Trivia items are linked to AST nodes and stored in the context.
+    - rewrite the code based on the AST, trivia and formatting settings.
+- merge the printed code of all code paths back to a single file/fragment.
 
 The following sections describe the modules/function you will most likely be
 interested in looking at to get started.
@@ -237,12 +284,6 @@ The [CodeFormatter.fsx](src/Fantomas/CodeFormatter.fsx) script file
 allows you to test the code formatting behavior. See the function `formatSrc: string -> unit`
 that formats the string in input and prints it.
 
-### Contribution examples
-The time it took to contribute is sometimes mentioned, as a side note.
-
-#### Fixing code generation
- - Record type formatting generated invalid F# code in some cases ([#197](https://github.com/dungpa/fantomas/pull/197)) - (2h fix)
-
 ## Credits
 We would like to gratefully thank the following persons for their contributions.
  - [Eric Taucher](https://github.com/EricGT)

RELEASE_NOTES.md

@@ -1,5 +1,19 @@
-### 3.0.1 - 11/2019
-* In development
+### 3.1.0 - 11/2019
+* Fix invalid code generated after multiline string when other expressions exist on same line. [#545](https://github.com/fsprojects/fantomas/issues/545)
+* Fix Trivia before elif generates invalid code due to missing indentation. [#527](https://github.com/fsprojects/fantomas/issues/527)
+* Fix Don't add additional newline between two and blocks. [#520](https://github.com/fsprojects/fantomas/issues/520)
+* Fix Print line comment after `{` [#517](https://github.com/fsprojects/fantomas/issues/517)
+* Fix Formatting document removes '#if DEBUG' and '#endif'. [#512](https://github.com/fsprojects/fantomas/issues/512)
+* Fix Some unicode control characters are incorrectly formatted. [#506](https://github.com/fsprojects/fantomas/issues/506)
+* Fix New empty line inserted preceding module attribute. [#505](https://github.com/fsprojects/fantomas/issues/505)
+* Fix Weird indentation/breaks with lambda in pipeline. [#503](https://github.com/fsprojects/fantomas/issues/503)
+* Fix Sufficiently indent match case bodies for other indentation lengths than 4. [#502](https://github.com/fsprojects/fantomas/issues/502)
+* Fix `--noSpaceBeforeColon` doesn't work. [#499](https://github.com/fsprojects/fantomas/issues/499)
+* Fix Invalid code produced when wrapping method call to new line. [#498](https://github.com/fsprojects/fantomas/issues/498)
+* Fix Indexer usage fails to parse. [#497](https://github.com/fsprojects/fantomas/issues/497)
+* Use FCS 33.0.0. [pull/568](https://github.com/fsprojects/fantomas/pull/568)
+* Use dotnet tools [pull/558](https://github.com/fsprojects/fantomas/pull/558)
+* Add `--maxIfThenElseShortWidth` option, see [documentation](https://github.com/fsprojects/fantomas/blob/master/docs/Documentation.md)
 
 ### 3.0.0 - 10/2019
 * Use FCS 32.0.0. [490b121af427ec4f6eba94f6d6d08cf3f91e04c8](https://github.com/fsprojects/fantomas/pull/434/commits/490b121af427ec4f6eba94f6d6d08cf3f91e04c8)

docs/Documentation.md

@@ -53,7 +53,7 @@ To illustrate, here is a code fragment with `--indent 2`:
 	```
  - `--pageWidth <number>`: `number` has to be an integer greater or equal to 60.
 This preference sets the column where we break F# constructs into new lines.
-The default value is 80. To see its effects, please take a look at some [output files](tests/stackexchange_output) with `--pageWidth 90` preference.
+The default value is 120. To see its effects, please take a look at some [output files](tests/stackexchange_output) with `--pageWidth 90` preference.
 
  - `--semicolonEOL`: add semicolons at the end of lines e.g.
 

fake-sample/.config/dotnet-tools.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "fake-cli": {
+      "version": "5.18.3",
+      "commands": [
+        "fake"
+      ]
+    }
+  }
+}

fake-sample/README.md

@@ -1,9 +1,14 @@
-# FAKE sample
+# FAKE sample - .NET Core 3
 
-Install FAKE locally:
+1. Restore FAKE locally:
 
-`dotnet tool install --tool-path ".fake" fake-cli --add-source https://api.nuget.org/v3/index.json --framework netcoreapp2.1`
+> dotnet tool restore
 
-Execute script:
+This was installed by:
 
-`.fake\fake.exe run script.fsx -t Format` or `.fake/fake run script.fsx -t Format`
+> dotnet new tool-manifest
+> dotnet tool install fake-cli
+
+2. Execute script:
+
+> dotnet fake run script.fsx -t Format

fake-sample/script.fsx

@@ -1,6 +1,5 @@
 #r "paket:
-nuget FSharp.Core
-nuget Fantomas 3.0.0-beta-001
+nuget Fantomas 3.1.0
 nuget Fake.Core.Target //"
 #load "./.fake/script.fsx/intellisense.fsx"
 
@@ -9,19 +8,17 @@ open Fake.IO.Globbing.Operators
 open Fantomas.FakeHelpers
 open Fantomas.FormatConfig
 
-let fantomasConfig =
-    { FormatConfig.Default with
-            ReorderOpenDeclaration = true }
+let fantomasConfig = { FormatConfig.Default with ReorderOpenDeclaration = true }
 
 Target.create "CheckCodeFormat" (fun _ ->
-    !! "*.fs"
+    !!"*.fs"
     |> checkCode fantomasConfig
-)
+    |> Async.RunSynchronously)
 
 Target.create "Format" (fun _ ->
-    !! "*.fs"
+    !!"*.fs"
     |> formatCode fantomasConfig
-    |> printfn "Formatted files: %A"
-)
+    |> Async.RunSynchronously
+    |> printfn "Formatted files: %A")
 
-Target.runOrList()
+Target.runOrList()