@@ -20,7 +20,7 @@ Our default, somewhat-arbitrary initial goal for a library is 90% code coverage.
## Issues
Issues are opened for a library when a cursory examination of its code coverage reveal that there are likely still some meaningful gaps that need to be addressed. We welcome contributions to our test suites to help address these gaps and close these issues. Many of these issues are marked as [up-for-grabs](https://github.com/dotnet/corefx/labels/up-for-grabs).
Issues are opened for a library when a cursory examination of its code coverage reveal that there are likely still some meaningful gaps that need to be addressed. We welcome contributions to our test suites to help address these gaps and close these issues. Many of these issues are marked as [up-for-grabs](https://github.com/dotnet/runtime/labels/up-for-grabs).
An issue need not be addressed in its entirety. We happily accept contributions that improve our tests and work towards improving code coverage numbers even if they only incrementally improve the situation.
...
...
@@ -58,6 +58,6 @@ Some of the libraries for which contracts and tests live in the corefx repo are
If the test project does not set the property `TestRuntime` to `true` and you want to collect code coverage that includes types in System.Private.CoreLib.dll add `/p:TestRuntime=true` to the coverage build command listed above.
If you want to get coverage report against a private build of System.Private.CoreLib follow the steps outlined at [Testing with Private CoreClr Bits](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md#testing-with-private-coreclr-bits).
If you want to get coverage report against a private build of System.Private.CoreLib follow the steps outlined at [Testing with Private CoreClr Bits](../project-docs/developer-guide.md#testing-with-private-coreclr-bits).
The build and test projects take care of copying assemblies and PDBs as needed for coverage runs. The resulting code coverage report should now also include details for System.Private.CoreLib.
@@ -66,7 +66,7 @@ For more information about the different options when building, run `build.cmd -
### Running tests from the command line
From the root, use `build.cmd -test`.
For more details, or to test an individual project, see the [developer guide topic](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md).
For more details, or to test an individual project, see the [developer guide topic](../project-docs/developer-guide.md).
### Running tests from Visual Studio
...
...
@@ -90,7 +90,7 @@ For more details, or to test an individual project, see the [developer guide top
VS Test Explorer support is limited to the .NET Core. To switch between Configurations (Debug / Release), Visual Studio needs to be reopened with the command above together with the additional `--configuration/-c` option.
For advanced debugging using WinDBG see [Debugging CoreFX on Windows](https://github.com/dotnet/corefx/blob/master/Documentation/debugging/windows-instructions.md)
For advanced debugging using WinDBG see [Debugging CoreFX on Windows](../debugging/windows-instructions.md)
### Notes
* At any given time, the corefx repo might be configured to use a [more recent compiler](../../../DotnetCLIVersion.txt) than
-[Determining versions and targets](#determining-versions-and-targets)
...
...
@@ -31,7 +31,7 @@ the implementation without compat concerns in future releases.
- If the library is not part of netstandard
- If package dependencies are changed then your target framework should be the minimum target framework that supports all your package dependencies.
- If your package depends directly on runtime changes or library changes that ship with the runtime (i.e. System.Private.CoreLib) then your target framework should be `netstandard`.
- When targeting `netstandardX` your new API must be supported by all target frameworks that map to that netstandard version (see [mapping table](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/net-platform-standard.md#mapping-the-net-platform-standard-to-platforms)). If not bump the version to the minimum netstandard version that supports this API on all frameworks that map to that netstandard version.
- When targeting `netstandardX` your new API must be supported by all target frameworks that map to that netstandard version (see [mapping table][net-standard table]). If not bump the version to the minimum netstandard version that supports this API on all frameworks that map to that netstandard version.
### Determine library version
- If targeting netstandard
...
...
@@ -49,13 +49,13 @@ the implementation without compat concerns in future releases.
**Update pkg**
- If changing the target framework
- Update `SupportedFramework` metadata on the ref ProjectReference to declare the set of concrete platforms you expect your library to support. (see [Specific platform mappings](https://github.com/dotnet/corefx/blob/master/Documentation/architecture/net-platform-standard.md#nuget)). Generally will be a combination of netcoreapp2.x, netfx46x, and/or `$(AllXamarinFrameworks)`.
- Update `SupportedFramework` metadata on the ref ProjectReference to declare the set of concrete platforms you expect your library to support. (see [Specific platform mappings][net-standard table]). Generally will be a combination of netcoreapp2.x, netfx46x, and/or `$(AllXamarinFrameworks)`.
- If assembly or package version is updated the package index needs to be updated by running
- Set `TargetGroup` which will generally match the `TargetGroup` in the src library build configuration. (ex: [System.Runtime\tests\Configurations.props](https://github.com/dotnet/corefx/blob/master/src/System.Runtime/tests/Configurations.props#L3))
- Add new test code following [conventions](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/project-guidelines.md#code-file-naming-conventions) for new files to that are specific to the new target framework.
- Add new test code following [conventions](project-guidelines.md#code-file-naming-conventions) for new files to that are specific to the new target framework.
- To run just the new test configuration run `dotnet msbuild <Library>.csproj /t:RebuildAndTest /p:TargetGroup=<TargetGroup>`
## FAQ
...
...
@@ -81,3 +81,6 @@ _**What to do if you are moving types down into a lower contract?**_
If you are moving types down you need to version both contracts at the same time and temporarily use
project references across the projects. You also need to be sure to leave type-forwards in the places
where you removed types in order to maintain back-compat.
@@ -5,7 +5,7 @@ Different applications have different needs when it comes to performance. For l
Much has been written about writing high-performance code in C#. This page provides links to some of that material and will expand over time as additional resources are found and identified as being relevant and useful.
You can read [CoreCLR Performance Requirements](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/performance-guidelines.md) to learn more.
You can read [CoreCLR Performance Requirements](../../coreclr/project-docs/performance-guidelines.md) to learn more.
This document provides the steps you need to take to update the reference assembly when adding new **public** APIs to an implementation assembly (post [API Review](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/adding-api-guidelines.md)).
## For most assemblies within corefx
1) Implement the API in the source assembly and [build it](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md#building-individual-libraries).
1) Implement the API in the source assembly and [build it](../project-docs/developer-guide.md#building-individual-libraries).
2) Run the following command (from the src directory) `msbuild /t:GenerateReferenceSource` to update the reference assembly**.
3) Navigate to the ref directory and build the reference assembly.
4) Add, build, and run tests.
...
...
@@ -11,6 +11,6 @@ This document provides the steps you need to take to update the reference assemb
## For System.Runtime
These steps can also be applied to some unique assemblies which depend on changes in System.Private.Corelib coming from [coreclr](https://github.com/dotnet/coreclr)(partial facades like [System.Memory](https://github.com/dotnet/corefx/blob/83711167ee74d2e87cf2d5ed3508c94044bb7edc/src/System.Memory/src/System.Memory.csproj#L6), for example).
1) Build coreclr release.
2) Build corefx release with coreclr bits (see [Testing with private CoreCLR bits](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/developer-guide.md#testing-with-private-coreclr-bits) for more details).
2) Build corefx release with coreclr bits (see [Testing with private CoreCLR bits](../project-docs/developer-guide.md#testing-with-private-coreclr-bits) for more details).
3) Run `msbuild /t:GenerateReferenceSource /p:ConfigurationGroup=Release` from the System.Runtime/ref directory.
4) Filter out all unrelated changes and extract the changes you care about (ignore certain attributes being removed). Generally, this step is not required for other reference assemblies.
@@ -13,4 +13,4 @@ The crash dump can then be located via this unique identifier from the Dumpling
Note that, while Dumpling archives the crash dumps for a long time, the Jenkins CI logs (containing the test info and the crash dump identifier) are not persisted for more than a few days.
Debugging crash dumps is a fairly involved process. Windows crash dumps are well-supported using existing and documented tools like Visual Studio, WinDBG, and SOS. The instructions for Unix platforms are complicated, and are documented [here](https://github.com/dotnet/corefx/blob/master/Documentation/debugging/unix-instructions.md#debugging-core-dumps-with-lldb).
Debugging crash dumps is a fairly involved process. Windows crash dumps are well-supported using existing and documented tools like Visual Studio, WinDBG, and SOS. The instructions for Unix platforms are complicated, and are documented [here](../debugging/unix-instructions.md#debugging-core-dumps-with-lldb).
@@ -6,7 +6,7 @@ CoreFX can be debugged on unix using both lldb and visual studio code
## Using lldb and SOS
- Run the test using msbuild at least once with `/t:BuildAndTest`.
-[Install version 3.9 of lldb](https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md#debugging-core-dumps-with-lldb) and launch lldb with dotnet as the process and arguments matching the arguments used when running the test through msbuild.
-[Install version 3.9 of lldb](../../coreclr/building/debugging-instructions.md#debugging-core-dumps-with-lldb) and launch lldb with dotnet as the process and arguments matching the arguments used when running the test through msbuild.
- Load the sos plugin using `plugin load libsosplugin.so`.
- Type `soshelp` to get help. You can now use all sos commands like `bpmd`.
...
...
@@ -29,7 +29,7 @@ It is also possible to debug .NET Core crash dumps using lldb and SOS. In order
- The crash dump file. We have a service called "Dumpling" which collects, uploads, and archives crash dump files during all of our CI jobs and official builds.
- On Linux, there is an utility called `createdump` (see [doc](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md"doc")) that can be setup to generate core dumps when a managed app throws an unhandled exception or faults.
- On Linux, there is an utility called `createdump` (see [doc](../../coreclr/botr/xplat-minidump-generation.md"doc")) that can be setup to generate core dumps when a managed app throws an unhandled exception or faults.
- Matching coreclr/corefx runtime bits from the crash. To get these, you should either:
- Download the matching Jenkins archive onto your repro machine.
- Check out the coreclr and corefx repositories at the appropriate commit and re-build the necessary portions.
You can Debug .NET Core via Visual Studio or WinDBG.
For Visual Studio debugging, follow the instructions at [Debugging tests in Visual Studio](https://github.com/dotnet/corefx/blob/master/Documentation/building/windows-instructions.md) to run and debug tests.
For Visual Studio debugging, follow the instructions at [Debugging tests in Visual Studio](../building/windows-instructions.md) to run and debug tests.
For bugs that cannot be reproduced within Visual Studio (certain low-probability race conditions, SafeHandle life-time problems, etc) you will need to use WinDBG.
## Required Software
...
...
@@ -150,7 +150,7 @@ The following EventSources are built-in to CoreFX. The ones that are not marked
#### System.Net namespaces
Helper scripts are available at https://github.com/dotnet/corefx/tree/master/src/Common/tests/Scripts/Tools. Run `net_startlog.cmd` as Administrator, run the application, then run `net_stoplog.cmd`. Open the `.etl` file with PerfView.
Helper scripts are available at https://github.com/dotnet/runtime/tree/master/src/libraries/Common/tests/Scripts/Tools. Run `net_startlog.cmd` as Administrator, run the application, then run `net_stoplog.cmd`. Open the `.etl` file with PerfView.
This document describes contribution guidelines that are specific to CoreFX. Please read [.NET Core Guidelines](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md) for more general .NET Core contribution guidelines.
This document describes contribution guidelines that are specific to CoreFX. Please read [.NET Core Guidelines](../../coreclr/project-docs/contributing.md) for more general .NET Core contribution guidelines.
@@ -10,29 +10,29 @@ As noted above, we don't close issues just because we don't plan to address them
2. Cross cutting work better suited for another team. Sometimes the line between the framework, languages and runtime blurs. For some issues, we may feel that the work is better suited for the runtime team, language team or other partner. In these cases, we'll close the issue and open it with the partner team. If they end up not deciding to take on the issue, we can reconsider it here.
3. Nebulous and Large open issues. Large open issues are sometimes better suited for [User Voice](http://visualstudio.uservoice.com/forums/121579-visual-studio/category/31481--net), especially when the work will cross the boundaries of the framework, language and runtime. A good example of this is the SIMD support we recently added to CoreFx. This started as a [User Voice request](https://visualstudio.uservoice.com/forums/121579-visual-studio-2015/suggestions/2212443-c-and-simd), and eventually turned into work for both the core libraries and runtime.
Sometimes after debate, we'll decide an issue isn't a good fit for CoreFx. In that case, we'll also close it. Because of this, we ask that you don't start working on an issue until it's tagged with [up-for-grabs](https://github.com/dotnet/corefx/labels/up-for-grabs) or [api-approved](https://github.com/dotnet/corefx/labels/api-approved). Both you and the team will be unhappy if you spend time and effort working on a change we'll ultimately be unable to take. We try to avoid that.
Sometimes after debate, we'll decide an issue isn't a good fit for CoreFx. In that case, we'll also close it. Because of this, we ask that you don't start working on an issue until it's tagged with [up-for-grabs](https://github.com/dotnet/runtime/labels/up-for-grabs) or [api-approved](https://github.com/dotnet/runtime/labels/api-approved). Both you and the team will be unhappy if you spend time and effort working on a change we'll ultimately be unable to take. We try to avoid that.
### Labels
We use GitHub [labels](https://github.com/dotnet/corefx/labels) on our issues in order to classify them. We have the following categories per issue:
***Area**: These area-* labels (e.g. [area-System.Collections](https://github.com/dotnet/corefx/labels/area-System.Collections)) call out the assembly or assemblies the issue applies to. In addition to labels per assembly, we have a few other area labels: [area-Infrastructure](https://github.com/dotnet/corefx/labels/area-Infrastructure), for issues that relate to our build or test infrastructure, and [area-Meta](https://github.com/dotnet/corefx/labels/area-Meta) for issues that deal with the repository itself, the direction of the .NET Core Platform, our processes, etc. See [full list of areas](#areas).
We use GitHub [labels](https://github.com/dotnet/runtime/labels) on our issues in order to classify them. We have the following categories per issue:
***Area**: These area-* labels (e.g. [area-System.Collections](https://github.com/dotnet/runtime/labels/area-System.Collections)) call out the assembly or assemblies the issue applies to. In addition to labels per assembly, we have a few other area labels: [area-Infrastructure](https://github.com/dotnet/runtime/labels/area-Infrastructure), for issues that relate to our build or test infrastructure, and [area-Meta](https://github.com/dotnet/runtime/labels/area-Meta) for issues that deal with the repository itself, the direction of the .NET Core Platform, our processes, etc. See [full list of areas](#areas).
***Issue Type**: These labels classify the type of issue. We use the following types:
*[bug](https://github.com/dotnet/corefx/labels/bug): Bugs in an assembly.
* api-* ([api-approved](https://github.com/dotnet/corefx/labels/api-approved), [api-needs-work](https://github.com/dotnet/corefx/labels/api-needs-work), [api-ready-for-review](https://github.com/dotnet/corefx/labels/api-ready-for-review)): Issues which would add APIs to an assembly (see [API Review process](api-review-process.md) for details).
*[enhancement](https://github.com/dotnet/corefx/labels/enhancement): Improvements to an assembly which do not add new APIs (e.g. performance improvements, code cleanup).
*[test bug](https://github.com/dotnet/corefx/labels/test%20bug): Bugs in the tests for a specific assembly.
*[test enhancement](https://github.com/dotnet/corefx/labels/test%20enhancement): Improvements in the tests for a specific assembly (e.g. improving test coverage).
*[documentation](https://github.com/dotnet/corefx/labels/documentation): Issues related to documentation (e.g. incorrect documentation, enhancement requests).
*[question](https://github.com/dotnet/corefx/labels/question): Questions about the product, source code, etc.
*[bug](https://github.com/dotnet/runtime/labels/bug): Bugs in an assembly.
* api-* ([api-approved](https://github.com/dotnet/runtime/labels/api-approved), [api-needs-work](https://github.com/dotnet/runtime/labels/api-needs-work), [api-ready-for-review](https://github.com/dotnet/runtime/labels/api-ready-for-review)): Issues which would add APIs to an assembly (see [API Review process](api-review-process.md) for details).
*[enhancement](https://github.com/dotnet/runtime/labels/enhancement): Improvements to an assembly which do not add new APIs (e.g. performance improvements, code cleanup).
*[test bug](https://github.com/dotnet/runtime/labels/test%20bug): Bugs in the tests for a specific assembly.
*[test enhancement](https://github.com/dotnet/runtime/labels/test%20enhancement): Improvements in the tests for a specific assembly (e.g. improving test coverage).
*[documentation](https://github.com/dotnet/runtime/labels/documentation): Issues related to documentation (e.g. incorrect documentation, enhancement requests).
*[question](https://github.com/dotnet/runtime/labels/question): Questions about the product, source code, etc.
***Other**:
*[easy](https://github.com/dotnet/corefx/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Aeasy%20no%3Aassignee) - Good for starting contributors.
*[up-for-grabs](https://github.com/dotnet/corefx/labels/up-for-grabs): Small sections of work which we believe are well scoped. These sorts of issues are a good place to start if you are new. Anyone is free to work on these issues.
*[needs more info](https://github.com/dotnet/corefx/labels/needs%20more%20info): Issues which need more information to be actionable. Usually this will be because we can't reproduce a reported bug. We'll close these issues after a little bit if we haven't gotten actionable information, but we welcome folks who have acquired more information to reopen the issue.
*[wishlist](https://github.com/dotnet/corefx/issues?q=is%3Aissue+is%3Aopen+label%3Awishlist) - Issues on top of our backlog we won't likely get to. Warning: Might not be easy.
*[easy](https://github.com/dotnet/runtime/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Aeasy%20no%3Aassignee) - Good for starting contributors.
*[up-for-grabs](https://github.com/dotnet/runtime/labels/up-for-grabs): Small sections of work which we believe are well scoped. These sorts of issues are a good place to start if you are new. Anyone is free to work on these issues.
*[needs more info](https://github.com/dotnet/runtime/labels/needs%20more%20info): Issues which need more information to be actionable. Usually this will be because we can't reproduce a reported bug. We'll close these issues after a little bit if we haven't gotten actionable information, but we welcome folks who have acquired more information to reopen the issue.
*[wishlist](https://github.com/dotnet/runtime/issues?q=is%3Aissue+is%3Aopen+label%3Awishlist) - Issues on top of our backlog we won't likely get to. Warning: Might not be easy.
In addition to the above, we have a handful of other labels we use to help classify our issues. Some of these tag cross cutting concerns (e.g. [tenet-performance](https://github.com/dotnet/corefx/labels/tenet-performance)), whereas others are used to help us track additional work needed before closing an issue (e.g. [api-needs-exposed](https://github.com/dotnet/corefx/labels/api-needs-exposed)).
In addition to the above, we have a handful of other labels we use to help classify our issues. Some of these tag cross cutting concerns (e.g. [tenet-performance](https://github.com/dotnet/runtime/labels/tenet-performance)), whereas others are used to help us track additional work needed before closing an issue (e.g. [api-needs-exposed](https://github.com/dotnet/runtime/labels/api-needs-exposed)).
### Milestones
We use [milestones](https://github.com/dotnet/corefx/milestones) to prioritize work for each upcoming release to NuGet.org.
We use [milestones](https://github.com/dotnet/runtime/milestones) to prioritize work for each upcoming release to NuGet.org.
### Assignee
We assign each issue to assignee, when the assignee is ready to pick up the work and start working on it. If the issue is not assigned to anyone and you want to pick it up, please say so - we will assign the issue to you. If the issue is already assigned to someone, please coordinate with the assignee before you start working on it.
@@ -72,7 +72,7 @@ Here are the high level guidelines:
Feature owners reserve the right to call out what they don't want to support on .NET Core. Since .NET Core is a new platform, we don't want to penalize our ability to build a componentized and cross-platform stack by signing up for technologies that are expensive to bring into this world and we don't think are sensible for today's needs.
This list, while not complete, is meant as a reference point. We'll add to it as we refine our porting plan. Also, just because something is currently not implemented, doesn't imply it's intentionally unsupported. Feel free to [file an issue](https://github.com/dotnet/corefx/issues/new) to ask for specific APIs and technologies. Porting requests are generally marked as [port-to-core](https://github.com/dotnet/corefx/issues?q=is%3Aopen+is%3Aissue+label%3Aport-to-core).
This list, while not complete, is meant as a reference point. We'll add to it as we refine our porting plan. Also, just because something is currently not implemented, doesn't imply it's intentionally unsupported. Feel free to [file an issue](https://github.com/dotnet/runtime/issues/new) to ask for specific APIs and technologies. Porting requests are generally marked as [port-to-core](https://github.com/dotnet/runtime/issues?q=is%3Aopen+is%3Aissue+label%3Aport-to-core).
Binary Serialization is supported post 1.1, however we do not support cross-platform binary serialization. For new code you may want to consider other serialization approaches such as data contract serialization, XML serialization, JSON.NET, and protobuf-net.
When writing network related tests we try to avoid running tests against a remote endpoint if possible. We provide simple APIs to create a LoopbackServer and send responses. A high number of scenarios can be tested with it. For additional information see https://github.com/dotnet/corefx/blob/master/src/Common/tests/System/Net/Http/LoopbackServer.cs
When writing network related tests we try to avoid running tests against a remote endpoint if possible. We provide simple APIs to create a LoopbackServer and send responses. A high number of scenarios can be tested with it. For additional information see https://github.com/dotnet/runtime/blob/master/src/libraries/Common/tests/System/Net/Http/LoopbackServer.cs
Example (skipping additional usings and class scoping):
```cs
...
...
@@ -65,7 +65,7 @@ This doesn't mean that you should mark every test which executes against a remot
# Relay Server
For network related tests which needs to contact a remote endpoint instead of a LoopbackServer, you can use our Relay Servers. We invest in Infrastructure to provide these "safe" remote endpoints.
For more information see https://github.com/dotnet/corefx/blob/master/src/Common/tests/System/Net/Configuration.Http.cs
For more information see https://github.com/dotnet/runtime/blob/master/src/libraries/Common/tests/System/Net/Configuration.Http.cs
