Update Contributor and Developer Guides and other docs
authorRich Lander <rlander@microsoft.com>
Wed, 11 Mar 2015 17:50:06 +0000 (10:50 -0700)
committerRichard Lander <rlander@microsoft.com>
Sat, 30 May 2015 22:44:45 +0000 (15:44 -0700)
Contribution-Overview.md [deleted file]
Contribution-guidelines.md [deleted file]
Developer-Guide.md
Performance-Requirements.md [moved from Performance.md with 100% similarity]
Test-instructions.md [new file with mode: 0644]
Validating-changes.md [moved from Testing-across-repos.md with 55% similarity]

diff --git a/Contribution-Overview.md b/Contribution-Overview.md
deleted file mode 100644 (file)
index 8f63d4d..0000000
+++ /dev/null
@@ -1,54 +0,0 @@
-## Contribution Overview ##
-
-This repository contains source-code that produces CoreCLR runtime used by number of projects (e.g. Windows Phone, ASP.NET 5, to name a few) to enable execution of managed code. Equally important is to understand that both CoreCLR and Desktop CLR (part of the .NET Framework) are built from the same source code and this repository contains a subset of that source code - targeted to build CoreCLR. As a result, any contributions made to this repository can have a tremendous impact - within Microsoft and to its customers across the globe - and will be reviewed very closely.
-
-**Workflow**
-
-At a high-level, this is how the contribution workflow looks like:
-
-1. Create a fork of CoreCLR repository
-2. Create a branch off the master in your fork. Name it something that that makes sense, such as issue-123 or githubhandle-issue. This makes it easy for everyone to figure out what the branch is used for. It also makes it easier to isolate your change from incoming changes from the origin.
-3. For all the [architectures and build configurations on the supported OS platforms](https://github.com/dotnet/coreclr/wiki/Developer-Guide):
-       1. Make sure that the builds are clean.
-       2. Make sure that the tests are are passing.
-4. Add a new test corresponding to your change, if applicable, and making sure that it passes.
-5. Commit your changes and push your changes to your branch on GitHub
-6. Create a pull request against the **dotnet/coreclr** repository's **master** branch
-               
-The pull-request (PR) will go through the usual review process. Once PR request comes in, our CI (continuous integration) system will perform the required builds and run tests (including the ones you are expected to run) against it. If the builds are clean, tests are passing and **at-least 2 developers** (could be more, depending on the context and nature of the change) from the .NET Runtime team have signed off on the change, the PR will be approved and merged.
-
-If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.
-
-_Note:_ As we are working to bring up the Linux port of the repo, our CI system will also gate the PRs against Linux builds to ensure that they are not broken. Usually, a PR will not break the Linux build but this is to identify the one-off change that may. This will also enable us to bring the Linux developers the same engineering experience, as on other platforms, sooner.
-
-**Understanding the TFS-Git Mirror**
-
-As mentioned above, CoreCLR and Desktop CLR share the same source code. We want to ensure that innovations made in one can flow successfully to the other. It also means that they should flow out to our repo and likewise, any changes committed to the repo should flow back to our internal branches. To facilitate this, we have a TFS-Git bidirectional mirroring infrastructure that will propagate any changes from our Desktop CLR branches to the Git repo and vice-versa.
-
-The mirroring infrastructure uses the following hint files to mirror a given TFS folder into GitHub and back:
-
-1. `.gitmirror` - any folder containing this file will **only** have its contained files mirrored. Subfolders are **not** mirrored.
-2. `.gitmirrorall` - any folder containing this file will have all of its files **and** subfolders mirrored recursively. The subfolders do not need to have any hint files.
-
-Thus, if you add a new folder to be included as part of the CoreCLR build, it will also need to have one of the two hint files mentioned above.
-
-In summary, the mirror enables your contribution to make its way into concrete products produced by the .NET team like CoreCLR, ASP.NET v5, Desktop CLR, to name a few.
-
-## Why CoreCLR (or, why not Desktop CLR)? ##
-
-Given that the sources in this repository only support building CoreCLR but are common to building both CoreCLR and Desktop CLR, it is intuitive to wonder why we do not build Desktop CLR in this repository as well.
-
-At a high-level, Desktop CLR is a way more complex product - it's build is very complex and produces way more artifacts (compared to CoreCLR) that are required for it to function completely and validate its feature set. Additionally, it also tightly integrated with the Desktop OS to enable various features. Simply porting the Desktop CLR build to happen in the open would be a multi-man year effort and unless all dependencies are ported, simply being able to build will not be of much practical use to the developer community.
-
-We have few key goals with making CoreCLR sources open:
-
-1. Address the curiosity of folks who are keen to understand the internals of managed code execution (and in turn, learn more about the guts of a virtual machine)
-2. Deliver a managed runtime that can support a variety of managed code execution scenarios, especially those that are required to support our modern web stack (i.e. ASP.NET 5).
-
-CoreCLR is a very self-contained managed runtime that helps address these goals, while at the same time, deliver a high degree of fidelity to support managed code execution across the board. It is quicker to port to different architectures and/or platforms (especially when compared with Desktop CLR) and does not have a complex install/validation process (it can be xcopied and executed). And given that it is built from the same sources as the Desktop CLR, folks who are interested to know learn more about low-level components (e.g. JIT, GC, TypeSystem, Assembly Binder/Loader to name a few), which are common to both, can use the sources in this repository to do so.
-
-**How to confirm if your change could regress Desktop CLR?**
-
-This is a work in progress. For now, we will review the changes closely to ensure that any potential for regressing the Desktop CLR is minimized. For you, the developer, it means that your change should be under a `#ifdef FEATURE_CORECLR`. 
-
-Long term, we are working on augmenting our CI system to perform Desktop CLR validation against the PR as well, in addition to PR reviews.
\ No newline at end of file
diff --git a/Contribution-guidelines.md b/Contribution-guidelines.md
deleted file mode 100644 (file)
index e316499..0000000
+++ /dev/null
@@ -1,79 +0,0 @@
-[CoreFx]: http://http://github.com/dotnet/corefx
-[CoreCLR]: http://http://github.com/dotnet/coreclr
-#Priorities
-The current priority for the team is open sourcing [.NET Core](http://blogs.msdn.com/b/dotnet/archive/2014/12/04/introducing-net-core.aspx).
-
-Because of this and the available bandwidth of our team we are going to have to balance the incoming PRs and issues with our current priority. 
-
-What this means is that we are putting in place a lightweight process for handling incoming PRs and issues to make sure the right set of people are working on the right set of PRs.
-
-#Bug bar
-In order for a change to be accepted it needs to have a **demonstrably broad impact** of a **mainline scenario** and be **low risk**.  The change must also meet these [performance requirements](https://github.com/dotnet/coreclr/wiki/Performance).
-
-While the definitions for mainline scenario and risk can be subjective, the area owner is the right person to ascertain them and provide a recommendation.
-
-#Dealing with issues and PRs
--      Please don’t surprise us with a large PR. Before you start work on a PR, please **file an issue** and **work with the area owner** to ensure the issue is a mainline issue and possible ways to fix it.
--      Once a PR is received, it will be assigned to the area owner who is going to evaluate the PR against the bug bar and decide if the change should be accepted
-
-#CoreCLR vs CoreFx
-[CoreCLR][CoreCLR] is the repository that contains the .NET runtime and the core library that is tied to the runtime (mscorlib).
-
-[CoreFx][CoreFx] is the repository that contains the new .NET Core libraries which is a better factored surface area that should serve us well going forward. 
-
-What that means is that some of the APIs that have ‘traditionally’ existed inside mscorlib (ie. System.Console) are now moving to their own separate assemblies.
-
-Because of backward compatibility (ie. Phone, full .NET Framework) where the APIs were present in mscorlib, those APIs can’t be removed from mscorlib. This leads to situations where the same (or very similar) code exists in both the [CoreCLR][CoreCLR] repository (as part of mscorlib) and in the [CoreFX][CoreFx] (as part of the new factored assembly).
-
-The rule of thumb is: **Start with the [CoreFX][CoreFx] repository for any managed API changes and the [CoreCLR][CoreCLR] repository for any runtime changes unless otherwise directed by the area owner.** 
-
-#Accepting contributions
-
-For general .NET Contribution guidelines, please refer to them [here](https://github.com/dotnet/corefx/wiki/Contributing).
-
-For coding guidelines for this repository, please do give priority to the current style of the project or file you're changing even if it diverges from the guidelines. 
-
-Because our code is mirrored with our internal source control, changes made to this repository are going to make their  way into future releases of the Desktop and Phone CLR.
-
-There are two broad categories of changes to the repository:
-
-##Code changes
-###New features / API surface area
-We are moving towards a well factored surface area that should serve us well going forward. With that in mind, we would like to have any new APIs added to the new surface area instead of mscorlib. This means that issues regarding new APIs should move to the [CoreFX][CoreFx] repository where it would go through the normal API review process.
-
-However, there are cases (we believe a small number) where changes should be done in mscorlib. We are going to address those on a case by case basis. 
-
-If you are unsure where the change should go, file an issue on the [CoreFX][CoreFx] repository.
-
-**For any feature that relates to the runtime (GC, JIT, etc) please continue to file issues on the [CoreCLR][CoreCLR] repository.**
-
-###Bug fixes
-There are generally two types of changes: functional and performance improvements.
-
-For both these kinds of changes, in order to consider accepting a PR for them, they need to show a **marked improvement** in a **mainline scenario** and have **low risk**.
-
-Bug fixes are generally about correcting a behavior for a give API/feature. The thing to keep in mind when fixing bugs is that there might be code out there that depends on the previous behavior of that API/feature. This means that bug fixes need to be done in such a way as to not impact the behavior of the API/feature on released versions of the .NET framework.
-
-Types of changes that would impact compatibility (the list is by no means complete)
-
-- A different behavior is observed after the change for an input
-- A new/different exception is thrown
-- An exception is no longer thrown
-- A new instance field is added to a type (impacts serialization)
-- Additional information can be found here: https://github.com/dotnet/corefx/wiki/Breaking-Changes 
-
-If there is no good way to guard against a breaking change we are going to have to turn down the PR.
-###Portability changes
-We are most likely going to accept any good changes to bring [CoreCLR][CoreCLR] to new platforms and operating systems.
-##Non-code changes
-###Formatting changes
-Because the code is mirrored with our internal source control system we would like to keep these kinds of changes to a minimum to avoid unnecessary merge conflicts.
-We are aware of the inconsistencies in our code base and are looking into ways of fixing that. While we are going to review each PR, the formatting changes are likely going to be turned down.
-
-###Typos
-Typos are embarrassing so we are going consider accepting most of these PRs.
-
-In order to keep the number of commits that fix typos we would like to ask that you either focus on a given area with your typos (ie. Mscorlib or the VM folder) or focus on one type of typo across the entire repository.
-
-###Changes to the build system
-We are going to consider accepting most of these assuming they provide value to the repository.
\ No newline at end of file
index 99add58..c0e0a7c 100644 (file)
-# Building the repository #
+Intro to CoreCLR
+================
 
-CoreCLR repo can be built from a regular, non-admin command prompt. Currently, the repo supports building CoreCLR.dll (and its various native binaries), mscorlib.dll and the accompanying tests for the following platforms and build configurations:
+CoreCLR is a self-contained .NET runtime that implements [ECMA 335](https://github.com/dotnet/coreclr/blob/master/Documentation/dotnet-standards.md). It is can be ported to multiple architectures and/or platforms. It support a variety of installation options, having no specific deployment requirements itself.
 
-**Windows**
+Project Goals and Priorities
+============================
 
-- X64 - Debug and Release
+Microsoft published CoreCLR to GitHub, with the following goals:
 
-We have work in progress to bring more tests online and support more platforms in the near future. As can be seen from the repo home page (the Linux build status labels), we are bringing up Linux support. Once the engineering support (e.g. build and validation) is functionally complete, we will share the details on how to build and test the product on Linux.
+- Establish a high-quality open source .NET implementation, with [CoreCLR](https://github.com/dotnet/coreclr) and [CoreFX](https://github.com/dotnet/corefx).
+- Port CoreCLR to Linux and OS X (already supported on Windows).
+- Support the community extending CoreCLR in various ways (e.g. [FreeBSD support](https://github.com/dotnet/coreclr/issues/455)).
 
-## Prerequisites ##
+The project has the following priorities, set by the .NET Team:
 
-1. Visual Studio must be installed. Supported versions:
-    - [Visual Studio Community 2013](http://go.microsoft.com/fwlink/?LinkId=517284) - **Free** for Open Source development!
-    - [Visual Studio 2013](http://www.visualstudio.com/downloads/download-visual-studio-vs) (Pro, Premium, Ultimate)
-    - Visual Studio Express isn't supported for building CoreCLR
-2. Install [Cmake](http://www.cmake.org/download/ "CMake") 3.0.2 for Windows and make sure it is present in PATH environment variable for the system.
-3. Powershell should be installed.
-4. Tools required to work with Git are installed (e.g. [Git for Windows](http://msysgit.github.io/), [GitHub for Windows](https://windows.github.com/))
+- x64 is the priority chip to support. x86 and ARM32 will follow.
+- Windows, Linux and OS X support have the same priority.
+- Porting is a higher priority (at this time) than new features.
 
-**Known Issues**
+Contributing
+============
 
-If you installed VS 2013 after VS 2012, then DIA SDK gets incorrectly installed to the VS 2012 install folder instead of VS 2013 install folder. This will result in a build break. To workaround this [issue](https://connect.microsoft.com/VisualStudio/feedback/details/814147/dia-sdk-installed-into-wrong-directory), copy `%program files (x86)%\Microsoft Visual Studio 11.0\DIA SDK` to  `%program files (x86)%\Microsoft Visual Studio 12.0\DIA SDK` and restart the build. More details are [here](http://support.microsoft.com/kb/3035999).
+Please read [Contributing](https://github.com/dotnet/coreclr/wiki/Contributing) to .NET Core before making your first contribution.
 
-**Git Configuration**
+Building the repository
+=======================
 
-The repository is configured to allow Git to make the right decision about handling CRLF. Specifically, if you are working on **Windows**, please ensure that **core.autocrlf** is set to **true**. On **non-Windows** platforms, please set it to **input**.
+The CoreCLR repo can be built from a regular, non-admin command prompt. The build produces CoreCLR (multiple native binaries), the mscorlib managed library and the accompanying tests. The repo can be built for the following platforms, using the provided instructions.
 
-**Building the repository**
+| Chip  | Windows | Linux | OS X |
+| :---- | :-----: | :---: | :--: |
+| x64   | &#x25CF;| &#x25D2;| &#x25D2; |                 
+| x86   | &#x25EF;| &#x25EF;| &#x25EF;|
+| ARM32 | &#x25EF; | &#x25EF;| &#x25EF; |
+|       | [Instructions][Windows-instructions] | [Instructions][Linux-instructions] | [Instructions][OSX-instructions] |  
 
-1. Fork the CoreCLR Repo
-2. Clone the forked repo on your development machine
-3. Open a new command prompt and navigate to the root of the cloned repo.
-4. Invoke "build.cmd clean"
+[Windows-instructions]: https://github.com/dotnet/coreclr/blob/master/Documentation/windows-instructions.md
+[Linux-instructions]: https://github.com/dotnet/coreclr/blob/master/Documentation/linux-instructions.md
+[OSX-instructions]: https://github.com/dotnet/coreclr/blob/master/Documentation/osx-instructions.md
 
-This will do a clean x64/Debug build of CoreCLR, its native components, Mscorlib and the tests. 
+The CoreCLR build and test suite is a work in progress, as are the [building and testing instructions](https://github.com/dotnet/coreclr/blob/master/Documentation/README.md#product-instructions). The .NET Core team and the community are improving Linux and OS X support on a daily basis are and adding more tests for all platforms. See [CoreCLR Issues](https://github.com/dotnet/coreclr/issues) to find out about specific work items or report issues.
 
+Understanding the TFS-Git Mirror
+================================
 
-- Product Binaries will be dropped in `<repo_root>\Binaries\Product\<arch>\<flavor>` folder. 
-- A Nuget package, Microsoft.Dotnet.CoreCLR, will also be created under `<repo_root>\Binaries\Product\<arch>\<flavor>\.nuget` folder. 
-- Test binaries will be dropped under `<repo_root>\Binaries\Tests\<arch>\<flavor>` folder
+The Microsoft team maintains a Microsoft-internal TFS server of CoreCLR. An automated system is used to flow changes in/out of GitHub. The mirroring infrastructure uses the following hint files to mirror a given TFS folder into GitHub and back:
 
-Doing **build /?** will give details on the supported parameters.
+1. `.gitmirror` - any folder containing this file will **only** have its contained files mirrored. Subfolders are **not** mirrored.
+2. `.gitmirrorall` - any folder containing this file will have all of its files **and** subfolders mirrored recursively. The subfolders do not need to have any hint files.
 
-
-## Building and running tests ##
-
-**Building Tests**        
-
-In a clean command prompt, issue the following command: 
-
-    <repo_root>\tests\buildtest.cmd x64 release clean
-
-**Note:** The above command (or building from the repo_root) must be done once, at the least, to ensure that all test dependencies are initialized correctly. 
-
-In Visual Studio, open `<repo_root>\tests\src\AllTestProjects.sln`, build all the test projects or the one required.
-
-**Running Tests**
-
-In a clean command prompt: `<repo_root>\tests\runtest.cmd x64 release <Absolute path to previously built product binaries>`
-
-This will generate the report named as `TestRun_<arch>_<flavor>.html` (e.g. `TestRun_x64__release.html`) in the current folder. It will also copy all the test dependencies to the folder passed at the command line.
-
-**Investigating Test Failures**
-
-Upon completing a test run, you may find one or more tests have failed.
-
-The output of the Test will be available in Test reports directory, but the default the directory would be something like is `<repo_root>\binaries\tests\x64\debug\Reports\Exceptions\Finalization`.
-
-There are 2 files of interest: 
-
-- `Finalizer.output.txt` - Contains all the information logged by the test.
-- `Finalizer.error.txt`  - Contains the information reported by CoreRun.exe (which executed the test) when the test process crashes.
-
-**Rerunning a failed test**
-
-If you wish to re-run a failed test, please follow the following steps:
-
-1. Set an environment variable, `CORE_ROOT`, pointing to the path to product binaries that was passed to runtest.cmd. The command to set this environment variable is also specified in the test report for a failed test.
-2. Next, run the failed test, the command to which is also present in the test report for a failed test. It will be something like `<repo_root>\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd`.
-
-If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug <debuggerFullPath>` to the test command. For example:
-
-
-     <repo_root>\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd -debug <debuggerFullPath>
-    
-**Modifying a test**
-
-If test changes are needed, make the change and build the test project. This will binplace the binaries in test binaries folder (e.g. `<repo_root>\binaries\tests\x64\debug\Exceptions\Finalization`). At this point, follow the steps to re-run a failed test to re-run the modified test.
-
-**Authoring Tests (in VS)**
-
-1. Use an existing test such as `<repo_root>\tests\src\Exceptions\Finalization\Finalizer.csproj` as a template and copy it to a new folder under `<repo_root>\tests\src`.
-2. Add the project of the new test to `<repo_root>\tests\src\AllTestProjects.sln` in VS
-3. Add source files to this newly added project.
-4. Indicate the success of the test by returning `100`.
-5. Add the .NET CoreFX contract references, as required, via the Nuget Package Manager in Visual Studio. *Make sure this does not change the csproj. If it does, then undo the change in the csproj.*
-6. Add any other projects as a dependency, if needed.
-7. Build the test.
-8. Follow the steps to re-run a failed test to validate the new test.
-
-
-## Debugging ##
-
-**Debugging CoreCLR**
-
-
-
-1. Perform a build of the repo.
-2. Open <repo_root>\binaries\Cmake\CoreCLR.sln in VS.
-3. Right click the INSTALL project and choose ‘Set as StartUp Project’
-4. Bring up the properties page for the INSTALL project
-5. Select Configuration Properties->Debugging from the left side tree control
-6. Set Command=`$(SolutionDir)..\product\$(Platform)\$(Configuration)\corerun.exe`
-       1. This points to the folder where the built runtime binaries are present.
-7. Set Command Arguments=`<managed app you wish to run>` (e.g. HelloWorld.exe)
-8. Set Working Directory=`$(SolutionDir)..\product\$(Platform)\$(Configuration)`
-       1. This points to the folder containing CoreCLR binaries.
-9. Press F11 to start debugging at wmain in corerun (or set a breakpoint in source and press F5 to run to it)
-       1. As an example, set a breakpoint for the EEStartup function in ceemain.cpp to break into CoreCLR startup.
-
-Steps 1-8 only need to be done once, and then (9) can be repeated whenever you want to start debugging. The above can be done with Visual Studio 2013.
-
-**Debugging Mscorlib and/or managed application**
-
-To step into and debug managed code of Mscorlib.dll (or the managed application being executed by the runtime you built), using Visual Studio, is something that will be supported with Visual Studio 2015. We are actively working to enable this support. 
-
-Until then, you can use [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) (an extension to WinDbg to support managed debugging) to step in and debug the generated managed code. This is what we do on the .NET Runtime team as well :)
\ No newline at end of file
+Thus, if you add a new folder to be included as part of the CoreCLR build, it will also need to have one of the two hint files mentioned above.
\ No newline at end of file
similarity index 100%
rename from Performance.md
rename to Performance-Requirements.md
diff --git a/Test-instructions.md b/Test-instructions.md
new file mode 100644 (file)
index 0000000..d1aee5a
--- /dev/null
@@ -0,0 +1,62 @@
+These instructions will lead you through testing CoreCLR on Windows. The tests are not fully supported on Linux and OS X and will be updated when they are. 
+
+Building and running tests
+==========================
+
+**Building Tests**        
+
+In a clean command prompt, issue the following command: 
+
+    C:\git\coreclr>tests\buildtest.cmd clean
+
+**buildtest /?** will list supported parameters.
+
+**Note:** The above command (or building from the repo_root) must be done once, at the least, to ensure that all test dependencies are initialized correctly. 
+
+In Visual Studio, open `<repo_root>\tests\src\AllTestProjects.sln`, build all the test projects or the one required.
+
+**Running Tests**
+
+In a clean command prompt: `<repo_root>\tests\runtest.cmd`
+
+**runtest /?** will list supported parameters.
+
+This will generate the report named as `TestRun_<arch>_<flavor>.html` (e.g. `TestRun_x64__release.html`) in the current folder. It will also copy all the test dependencies to the folder passed at the command line.
+
+**Investigating Test Failures**
+
+Upon completing a test run, you may find one or more tests have failed.
+
+The output of the Test will be available in Test reports directory, but the default the directory would be something like is `<repo_root>\binaries\tests\x64\debug\Reports\Exceptions\Finalization`.
+
+There are 2 files of interest: 
+
+- `Finalizer.output.txt` - Contains all the information logged by the test.
+- `Finalizer.error.txt`  - Contains the information reported by CoreRun.exe (which executed the test) when the test process crashes.
+
+**Rerunning a failed test**
+
+If you wish to re-run a failed test, please follow the following steps:
+
+1. Set an environment variable, `CORE_ROOT`, pointing to the path to product binaries that was passed to runtest.cmd. The command to set this environment variable is also specified in the test report for a failed test.
+2. Next, run the failed test, the command to which is also present in the test report for a failed test. It will be something like `<repo_root>\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd`.
+
+If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug <debuggerFullPath>` to the test command. For example:
+
+
+     <repo_root>\binaries\tests\x64\debug\Exceptions\Finalization\Finalizer.cmd -debug <debuggerFullPath>
+    
+**Modifying a test**
+
+If test changes are needed, make the change and build the test project. This will binplace the binaries in test binaries folder (e.g. `<repo_root>\binaries\tests\x64\debug\Exceptions\Finalization`). At this point, follow the steps to re-run a failed test to re-run the modified test.
+
+**Authoring Tests (in VS)**
+
+1. Use an existing test such as `<repo_root>\tests\src\Exceptions\Finalization\Finalizer.csproj` as a template and copy it to a new folder under `<repo_root>\tests\src`.
+2. Add the project of the new test to `<repo_root>\tests\src\AllTestProjects.sln` in VS
+3. Add source files to this newly added project.
+4. Indicate the success of the test by returning `100`.
+5. Add the .NET CoreFX contract references, as required, via the Nuget Package Manager in Visual Studio. *Make sure this does not change the csproj. If it does, then undo the change in the csproj.*
+6. Add any other projects as a dependency, if needed.
+7. Build the test.
+8. Follow the steps to re-run a failed test to validate the new test.
\ No newline at end of file
similarity index 55%
rename from Testing-across-repos.md
rename to Validating-changes.md
index f6ccdea..68b0654 100644 (file)
@@ -1,5 +1,9 @@
-#How to run CoreFx tests on top of CoreCLR binaries
-If you want to validate the changes you have made to the CoreCLR repo you can do that by running the CoreFx tests on top of the newly build binaries (from the CoreCLR repo)
+We have ported very few of our CoreCLR and mscorlib tests to the repo. When we do, this topic will grow. Until then, the following technique is a good sanity test for your changes.
+
+Validating your changes using CoreFX
+====================================
+
+It may be valuable to use CoreFX tests to validate your changes to CoreCLR or mscorlib.
 
 In order to do this you need to create a file called `localpublish.props` under the `<repo root>\packages` folder.
 The contents of the file should look like this (make sure to update the version to the current version of the CoreCLR package used by CoreFx):
@@ -15,6 +19,6 @@ The contents of the file should look like this (make sure to update the version
       </ItemGroup>
     </Project>
 
-Once this file is there, subsequent builds of the CoreCLR repo are going to install the CoreCLR package into the location specified by `InstallLocation`.
+Once this file is there, subsequent builds of the CoreCLR repo will install the CoreCLR package into the location specified by `InstallLocation`.
 
-To run tests, follow the procedure for running tests in CoreFx
\ No newline at end of file
+To run tests, follow the procedure for running tests in CoreFX.
\ No newline at end of file