Better readme #150
Merged
Better readme #150
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jdodds
reviewed
Oct 16, 2019
jdodds
approved these changes
Oct 16, 2019
Content/Library/README.md
Outdated
Comment on lines
80
to
93
| - `Clean` - Cleans up artifact and temp directories | ||
| - `DotnetRestore` - Runs [dotnet restore](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-restore?tabs=netcore2x) on the [solution file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). | ||
| - [`DotnetBuild`](#Building) - Runs [dotnet build](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-build?tabs=netcore2x) on the [solution file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). | ||
| - `DotnetTest` - Runs [dotnet test](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-test?tabs=netcore21) on the [solution file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). | ||
| - `GenerateCoverageReport` - Code coverage is run during `DotnetTest` and this generates a report via [ReportGenerator](https://github.com/danielpalme/ReportGenerator) | ||
| - `WatchTests` - Runs [dotnet watch](https://docs.microsoft.com/en-us/aspnet/core/tutorials/dotnet-watch?view=aspnetcore-3.0) with the test projects. Useful for rapid feedback loops. | ||
| - `GenerateAssemblyInfo` - Generates [AssemblyInfo](https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualbasic.applicationservices.assemblyinfo?view=netframework-4.8) for libraries | ||
| - `DotnetPack` - Runs [dotnet pack](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-pack). This include running [SourceLink](https://github.com/dotnet/sourcelink) | ||
| - `SourcelinkTest` - Runs a Sourcelink Test tool to verify Sourcelinks were properly generated | ||
| - `PublishToNuget` - Publishes the nuget via [paket push](https://fsprojects.github.io/Paket/paket-push.html) | ||
| - `GitRelease` - Creates a commit message with the [Release Notes](https://fake.build/apidocs/v5/fake-core-releasenotes.html) and a git tag via the version in the `Release Notes` | ||
| - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any nuget packages | ||
| - `FormatCode` - Runs [Fantomas](https://github.com/fsprojects/fantomas) on the sln | ||
| - [`Release`](#Releasing) - Task that runs all release type tasks such as `PublishToNuget` `GitRelease` and `GitHubRelease`. Make sure to read [Releasing](#Releasing) to setup your environment correctly for releases. |
There was a problem hiding this comment.
Again, inconsistent in fragments vs. full sentences.
|
Using write-good [or VS Code plugin Write Good Linter] can help identify new areas of improvement in writing. (Though there's only a few items it's call outs as possible issues.) |
TheAngryByrd
pushed a commit
that referenced
this pull request
Oct 21, 2019
* MINOR: Better READMEs (#150)
andrewpucci
reviewed
Oct 22, 2019
| ### Environment Variables | ||
|
|
||
| - `CONFIGURATION` will set the [configuration](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-build?tabs=netcore2x#options) of the dotnet commands. If not set, it will default to Release. | ||
| - `CONFIGURATION=Debug ./build.sh` will result in `-c` additions to commands such as in `dotnet build -c Debug` | ||
| - `GITHUB_TOKEN` will be used to upload release notes and nuget packages to github. |
There was a problem hiding this comment.
Suggested change
| - `GITHUB_TOKEN` will be used to upload release notes and nuget packages to github. | |
| - `GITHUB_TOKEN` will be used to upload release notes and NuGet packages to GitHub. |
There was a problem hiding this comment.
Also, is it worth linking to a GitHub resource here on how to produce a GitHub token from your account? Perhaps folks won't be familiar with this?
There was a problem hiding this comment.
I do have it in the Releasing Section "Create a GitHub OAuth Token". Should I double up with it?
Content/Library/README.md
Outdated
| - `WatchTests` - Runs [dotnet watch](https://docs.microsoft.com/en-us/aspnet/core/tutorials/dotnet-watch?view=aspnetcore-3.0) with the test projects. Useful for rapid feedback loops. | ||
| - `GenerateAssemblyInfo` - Generates [AssemblyInfo](https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualbasic.applicationservices.assemblyinfo?view=netframework-4.8) for libraries | ||
| - `DotnetPack` - Runs [dotnet pack](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-pack). This include running [SourceLink](https://github.com/dotnet/sourcelink) | ||
| - `SourcelinkTest` - Runs a Sourcelink Test tool to verify Sourcelinks were properly generated |
There was a problem hiding this comment.
Suggested change
| - `SourcelinkTest` - Runs a Sourcelink Test tool to verify Sourcelinks were properly generated | |
| - `SourceLinkTest` - Runs a Source Link test tool to verify Source Links were properly generated |
| - `GenerateAssemblyInfo` - Generates [AssemblyInfo](https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualbasic.applicationservices.assemblyinfo?view=netframework-4.8) for libraries | ||
| - `DotnetPack` - Runs [dotnet pack](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-pack). This include running [SourceLink](https://github.com/dotnet/sourcelink) | ||
| - `SourcelinkTest` - Runs a Sourcelink Test tool to verify Sourcelinks were properly generated | ||
| - `PublishToNuget` - Publishes the nuget via [paket push](https://fsprojects.github.io/Paket/paket-push.html) |
There was a problem hiding this comment.
Suggested change
| - `PublishToNuget` - Publishes the nuget via [paket push](https://fsprojects.github.io/Paket/paket-push.html) | |
| - `PublishToNuGet` - Publishes the NuGet via [`paket push`](https://fsprojects.github.io/Paket/paket-push.html) |
There was a problem hiding this comment.
Also, I'm not sure what Publishes the NuGet means. Should this be Publishes to NuGet or Publishes the NuGet [something] instead?
Content/Library/README.md
Outdated
| - `SourcelinkTest` - Runs a Sourcelink Test tool to verify Sourcelinks were properly generated | ||
| - `PublishToNuget` - Publishes the nuget via [paket push](https://fsprojects.github.io/Paket/paket-push.html) | ||
| - `GitRelease` - Creates a commit message with the [Release Notes](https://fake.build/apidocs/v5/fake-core-releasenotes.html) and a git tag via the version in the `Release Notes` | ||
| - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any nuget packages |
There was a problem hiding this comment.
Suggested change
| - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any nuget packages | |
| - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any NuGet packages |
Content/Library/README.md
Outdated
| - `PublishToNuget` - Publishes the nuget via [paket push](https://fsprojects.github.io/Paket/paket-push.html) | ||
| - `GitRelease` - Creates a commit message with the [Release Notes](https://fake.build/apidocs/v5/fake-core-releasenotes.html) and a git tag via the version in the `Release Notes` | ||
| - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any nuget packages | ||
| - `FormatCode` - Runs [Fantomas](https://github.com/fsprojects/fantomas) on the sln |
There was a problem hiding this comment.
Maybe add a brief description of Fantomas? Like Runs Fantomas, a code formatter, on the solution, so they don't need to click through the link to understand what this is from a high level
| - Builds for both `net461` and `netstandard2.1` - [Target Frameworks](https://docs.microsoft.com/en-us/dotnet/standard/frameworks) | ||
| - To build for `net461` | ||
| - On windows: Have at least .NET Framework 4.6.1 installed | ||
| - On osx/linux: Have [mono](https://www.mono-project.com/download/stable/) installed |
There was a problem hiding this comment.
Suggested change
| - On osx/linux: Have [mono](https://www.mono-project.com/download/stable/) installed | |
| - On macOS/Linux: Have [mono](https://www.mono-project.com/download/stable/) installed |
| - On osx/linux: Have [mono](https://www.mono-project.com/download/stable/) installed | ||
| - To build for `netstandard2.1` | ||
| - Have [.NET core 3.0](https://dotnet.microsoft.com/download) installed | ||
| - [Sourcelink](https://github.com/dotnet/sourcelink) which enables a great source debugging experience for your users, by adding source control metadata to your built assets |
There was a problem hiding this comment.
Suggested change
| - [Sourcelink](https://github.com/dotnet/sourcelink) which enables a great source debugging experience for your users, by adding source control metadata to your built assets | |
| - [Source Link](https://github.com/dotnet/sourcelink) which enables a great source debugging experience for your users by adding source control metadata to your built assets |
|
|
||
| The bin of your new lib should look similar to: | ||
| ### Install the [dotnet template](https://docs.microsoft.com/en-us/dotnet/core/tools/custom-templates) from nuget: |
There was a problem hiding this comment.
Suggested change
| ### Install the [dotnet template](https://docs.microsoft.com/en-us/dotnet/core/tools/custom-templates) from nuget: | |
| ### Install the [dotnet template](https://docs.microsoft.com/en-us/dotnet/core/tools/custom-templates) from NuGet: |
|
|
||
| MacOS/Linux | Windows |
There was a problem hiding this comment.
Suggested change
| MacOS/Linux | Windows | |
| macOS/Linux | Windows |
| @@ -11,43 +11,74 @@ MacOS/Linux | Windows | |||
| [](https://travis-ci.org/MyGithubUsername/MyLib.1) | [](https://ci.appveyor.com/project/MyGithubUsername/MyLib.1) | |||
| [](https://travis-ci.org/MyGithubUsername/MyLib.1/builds) | [](https://ci.appveyor.com/project/MyGithubUsername/MyLib.1) | |||
|
|
|||
| --- | |||
| ## Nuget | |||
There was a problem hiding this comment.
Suggested change
| ## Nuget | |
| ## NuGet |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Proposed Changes
Updates the READMEs to reflect the Library/Console Application split.
Types of changes
What types of changes does your code introduce to MiniScaffold?
Put an
xin the boxes that applyChecklist
Put an
xin the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...