Cleaning up the documentation folder (#5928)
* Cleaning up the documentation folder This change cleans up the documentation folder in the CLI repo. The changes are the following: * Delete old content that is invalid moving forward. * Move cli-installation-scenarios to the `specs` sub-folder. * Add a sub-folder for documentation that deals with working with the repo * Add a general sub-folder * Finally, change the README.md to reflect this. Also, this change adds a document that covers CLI UX guidelines for authors of new commands. * Firt round of PR feedback changes
This commit is contained in:
Zlatko Knezevic
GitHub
parent
890676ad87
commit
09b6be5990
15 changed files with 267 additions and 201 deletions
75
Documentation/project-docs/developer-guide.md
Normal file
75
Documentation/project-docs/developer-guide.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
Developer Guide
|
||||
===============
|
||||
|
||||
## Prerequisites
|
||||
|
||||
In order to build .NET Command Line Interface, you need the following installed on you machine.
|
||||
|
||||
### For Windows
|
||||
|
||||
1. CMake (available from https://cmake.org/) on the PATH.
|
||||
2. git (available from http://www.git-scm.com/) on the PATH.
|
||||
|
||||
### For Linux
|
||||
|
||||
1. CMake (available from https://cmake.org/) is required to build the native host `corehost`. Make sure to add it to the PATH.
|
||||
2. git (available from http://www.git-scm.com/) on the PATH.
|
||||
3. clang (available from http://clang.llvm.org) on the PATH.
|
||||
|
||||
### For OS X
|
||||
|
||||
1. Xcode
|
||||
2. CMake (available from https://cmake.org/) on the PATH.
|
||||
3. git (available from http://www.git-scm.com/) on the PATH.
|
||||
4. Install OpenSSL (a .NET Core requirement)
|
||||
- brew install openssl
|
||||
- brew link --force openssl
|
||||
|
||||
## Building/Running
|
||||
|
||||
1. Run `build.cmd` or `build.sh` from the root depending on your OS. If you don't want to execute tests, run `build.cmd /t:Compile` or `./build.sh /t:Compile`.
|
||||
- To build the CLI in macOS Sierra, you need to set the DOTNET_RUNTIME_ID environment variable by running `export DOTNET_RUNTIME_ID=osx.10.11-x64`.
|
||||
2. Use `artifacts/{RID}/stage2/dotnet` to try out the `dotnet` command. You can also add `artifacts/{os}-{arch}/stage2` to the PATH if you want to use the build output when invoking `dotnet` from the current console.
|
||||
|
||||
## A simple test
|
||||
Using the `dotnet` built in the previous step:
|
||||
|
||||
1. `cd {new directory}`
|
||||
2. `dotnet new`
|
||||
3. `dotnet restore3`
|
||||
4. `dotnet run3`
|
||||
|
||||
## Running tests
|
||||
|
||||
1. To run all tests invoke `build.cmd` or `build.sh` which will build the product and run the tests.
|
||||
2. To run a specific test, cd into that test's directory and execute `dotnet test`. If using this approach, make sure to add `artifacts/{RID}/stage2` to your `PATH` and set the `NUGET_PACKAGES` environment variable to point to the repo's `.nuget/packages` directory.
|
||||
|
||||
##Adding a Command
|
||||
|
||||
The dotnet CLI supports several models for adding new commands:
|
||||
|
||||
0. In the CLI itself via `dotnet.dll`
|
||||
1. Through a `tool` NuGet package
|
||||
2. Through MSBuild tasks & targets in a NuGet package
|
||||
3. Via the user's `PATH`
|
||||
|
||||
### Commands in dotnet.dll
|
||||
Developers are generally encouraged to avoid adding commands to `dotnet.dll` or the CLI installer directly. This is appropriate for very general commands such as restore, build, publish, test, and clean, but is generally too broad of a distribution mechanism for new commands. Please create an issue and engage the team if you feel there is a missing core command that you would like to add.
|
||||
|
||||
### Tools NuGet packages
|
||||
Many existing extensions, including those for ASP.NET Web applications, extend the CLI using Tools NuGet packages. For an example of a working packaged command look at `TestAssets/TestPackages/dotnet-hello/v1/`.
|
||||
|
||||
### MSBuild tasks & targets
|
||||
NuGet allows adding tasks and targets to a project through a NuGet package. This mechanism, in fact, is how all .NET Core projects pull in the .NET SDK. Extending the CLI through this model has several advantages:
|
||||
|
||||
1. Targets have access to the MSBuild Project Context, allowing them to reason about the files and properties being used to build a particular project.
|
||||
2. Targets are not CLI-specific, making them easy to share across command-line and IDE environments
|
||||
|
||||
Commands added as targets can be invoked once the target project adds a reference to the containing NuGet package and restores.
|
||||
Targets are invoked by calling `dotnet msbuild /t:{TargetName}`
|
||||
|
||||
### Commands on the PATH
|
||||
The dotnet CLI considers any executable on the path named `dotnet-{commandName}` to be a command it can call out to.
|
||||
|
||||
## Things to Know
|
||||
- Any added commands are usually invoked through `dotnet {command}`. As a result of this, stdout and stderr are redirected through the driver (`dotnet`) and buffered by line. As a result of this, child commands should use Console.WriteLine in any cases where they expect output to be written immediately. Any uses of Console.Write should be followed by Console.WriteLine to ensure the output is written.
|
||||
45
Documentation/project-docs/issue-filing-guide.md
Normal file
45
Documentation/project-docs/issue-filing-guide.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
Filing issues for .NET Core CLI
|
||||
===============================
|
||||
|
||||
As you may notice based on our issues page, the CLI repo is what is known as a
|
||||
"high-profile" and "high-volume" repo; we
|
||||
get a lot of issues. This, in turn, may mean that some issues get
|
||||
lost in the noise and/or are not reacted on with the needed speed.
|
||||
|
||||
In order to help with the above situation, we need to have a certain way to file
|
||||
issues so that the core team of maintainers can react as fast as
|
||||
possible and can triage effectively.
|
||||
|
||||
The below steps are something that we believe is not a huge increase in process,
|
||||
but would help us react much faster to any issues that are filed.
|
||||
|
||||
1. Check if the [known issues](https://github.com/dotnet/core/blob/master/cli/known-issues.md) cover the issue you are running
|
||||
into. We are collecting issues that are known and that have workarounds, so it
|
||||
could be that you can get unblocked pretty easily.
|
||||
|
||||
4. /cc the person that the issue should be assigned to (or @blackdwarf) so that person
|
||||
would get notified. In this way the correct person can immediately jump on the
|
||||
issue and triage it.
|
||||
|
||||
5. For bugs, please be as concrete as possible on what is working, what
|
||||
is not working. Things like operating system, the version of the tools, the
|
||||
version of the installer and when you installed all help us determine the
|
||||
potential problem and allows us to easily reproduce the problem at hand.
|
||||
|
||||
6. For enhancements please be as concrete as possible on what is the addition
|
||||
you would like to see, what scenario it covers and especially why the current
|
||||
tools cannot satisfy that scenario.
|
||||
|
||||
Thanks and happy filing! :)
|
||||
|
||||
## Providing the repro for bugs
|
||||
For bugs, what we need more than anything is a good repro of the defective
|
||||
behavior. We would like to go towards the "clone, run, repro" model. In short:
|
||||
|
||||
1. If you find a bug, package up a repro in a git repo somewhere (GitHub is
|
||||
usually a good place :)).
|
||||
2. Inside the issue, specify what needs to be done (steps) to get an accurate
|
||||
repro of the bug. Ideally, this should be "here is how to build, these are the
|
||||
commands you run from the dotnet tools".
|
||||
3. We use the above to get the repro, investigate and fix!
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue