Add "recovering from failures" to documentation

[TheAngryByrd]

Is your feature request related to a problem? Please describe.

Based on @rmunn's comments in https://github.com/TheAngryByrd/MiniScaffold/pull/175#issuecomment-580043445, we should add documentation that specifies what you need to do in case of build failures.

Describe the solution you'd like

For each target in the list, show errors and what to do about them.

Also show scenarios where if PublishToNuGet works but GitHubReleases fails for some reason, the manual steps to sync up the rest of the targets.

Describe alternatives you've considered

Letting the user figure it out and suffer.

Additional context Add any other context or screenshots about the feature request here.

[rmunn]

I wonder if we should create build targets named FooOnly that run the Foo target with no dependencies. I've done this in my projects with the DotnetTest target, where I often want to run the tests over and over again (in a VS Code debugging session) without running the DotnetBuild target over and over because I haven't been changing the code, just adding breakpoints as I try to narrow down the cause of the bug. And it's nice to have the tests launch immediately when I hit F5 (which I configured to run the DotnetTestOnly target) rather than waiting half a minute for the build.

This would allow the "recovering from failure" docs to be simpler, as instead of saying "edit the script to comment out the dependency chain and then run targets Foo, Bar and Baz", the instructions could just be "once you've fixed the cause of the failure, run targets FooOnly, BarOnly and BazOnly in that order, then resume normal development."

The disadvantage is that some people might get used to running these FooOnly targets, such as DotnetTestOnly to start the tests faster, and then they'd forget that normal builds should run the dependencies. And then they'd wonder why their bugfix wasn't causing the tests to start passing again, not realizing that the bugfix wasn't being built.

Thoughts?

[TheAngryByrd]

I wonder if we should create build targets named FooOnly that run the Foo target with no dependencies. I've done this in my projects with the DotnetTest target, where I often want to run the tests over and over again (in a VS Code debugging session) without running the DotnetBuild target over and over because I haven't been changing the code, just adding breakpoints as I try to narrow down the cause of the bug. And it's nice to have the tests launch immediately when I hit F5 (which I configured to run the DotnetTestOnly target) rather than waiting half a minute for the build.

This would allow the "recovering from failure" docs to be simpler, as instead of saying "edit the script to comment out the dependency chain and then run targets Foo, Bar and Baz", the instructions could just be "once you've fixed the cause of the failure, run targets FooOnly, BarOnly and BazOnly in that order, then resume normal development."

The disadvantage is that some people might get used to running these FooOnly targets, such as DotnetTestOnly to start the tests faster, and then they'd forget that normal builds should run the dependencies. And then they'd wonder why their bugfix wasn't causing the tests to start passing again, not realizing that the bugfix wasn't being built.

Thoughts?

The way I currently handle things like this are to just run the commands. Like If I need to just test against a project I'll just cd tests/Project ; dotnet test that specific one. dotnet test should also work where the .sln file is located. This is a slippery slope argument but, where would we draw the line. Like should we have a dotnet build and dotnet test for every individual project? The dotnet CLI commands already handle this better than trying to put a facade on top I feel.

That being said, about the ones that have a more hard recovery mode. I'd again lean toward having people do it "manually" for now like running git tag v1.0.0 && git push && git push --tags and copying/pasting the CHANGELOG into the GitHub Release Notes. Mainly because if something automated went really wrong, I don't know if I could write a reasonable amount of code to get back to the super happy path we're trying to create.

[baronfel]

@rmunn speaking to your point about wanting to run the same target again and again, with no other dependencies, FAKE has a syntax for this: fake run build.fsx -s -t Build. The t for target, the s for 'single', meaning no dependencies.