Merge pull request #1879 from richlander/rich-docs-update

Move wiki files to corefx and coreclr repos

Author: richlander

CONTRIBUTING.md

@@ -1,11 +1,7 @@
 # Contributing
 
-See [Contributing] on the wiki for information about coding styles, source structure, making
-pull requests, and more.
+See [Contributing](Documentation/contributing.md) for information about coding styles, source structure, making pull requests, and more.
 
-[Contributing]: https://github.com/dotnet/corefx/wiki/Contributing
 # Developers
 
-See the [Developer Guide] for details about developing in this repo.
-
-[Developer Guide]: https://github.com/dotnet/corefx/wiki/Developer-Guide
+See the [Developer Guide](Documentation/developer-guide.md) for details about developing in this repo.

Documentation/README.md

@@ -0,0 +1,58 @@
+Documents Index
+===============
+
+Learn about .NET Core
+====================
+
+- [Brief Intro to .NET Core](https://github.com/dotnet/coreclr/blob/master/Documentation/dotnetcore-intro.md)
+- [[WIP] Official .NET Core Docs](http://dotnet.readthedocs.org)
+
+Get .NET Core
+=============
+
+- [Get .NET Core DNX SDK on Windows](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-dnx-windows.md)
+- [Get .NET Core DNX SDK on OS X](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-dnx-osx.md)
+- [Get .NET Core DNX SDK on Linux](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-dnx-linux.md)
+- [Get .NET Core (Raw) on Windows](https://github.com/dotnet/coreclr/blob/master/Documentation/get-dotnetcore-windows.md)
+
+Project Docs
+============
+
+- [Developer Guide](developer-guide.md)
+- [Project priorities](https://github.com/dotnet/coreclr/blob/master/Documentation/project-priorities.md)
+- [Contributing to CoreFX](contributing.md)
+- [Contributing to .NET Core](https://github.com/dotnet/coreclr/blob/master/Documentation/contributing.md)
+- [Contributing Workflow](https://github.com/dotnet/coreclr/blob/master/Documentation/contributing-workflow.md)
+- [Issue Guide](issue-guide.md)
+- [Branching Guide](branching-guide.md)
+- [API Review Process](api-review-process.md)
+- [Strong Name Signing](strong-name-signing.md)
+- [Open Source Signing](oss-signing.md)
+- [Repo Organization](repo-organization.md)
+
+Coding Guidelines
+=================
+
+- [C# coding style](coding-style.md)
+- [Framework Design Guidelines](framework-design-guidelines-digest.md)
+- [Cross-Platform Guidelines](cross-platform-guidelines.md)
+- [Performance Guidelines](performance-guidelines.md)
+- [Interop Guidelines](interop-guidelines.md)
+- [Breaking Changes](breaking-changes.md)
+- [Breaking Change Definitions](breaking-change-definitions.md)
+- [Breaking Change Rules](breaking-change-rules.md)
+
+Building from Source
+====================
+
+- [Building on Linux](linux-instructions.md)
+- [Code Coverage](code-coverage.md)
+
+Other Information
+=================
+
+- [CoreCLR Repo documentation](https://github.com/dotnet/coreclr/tree/master/Documentation)
+- [Porting to .NET Core](support-dotnet-core-instructions.md)
+- [.NET Standards (Ecma)](https://github.com/dotnet/coreclr/blob/master/Documentation/dotnet-standards.md)
+- [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
+- [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)

Documentation/api-review-process.md

@@ -0,0 +1,58 @@
+API Review Process
+==================
+
+The .NET Framework has a long standing history of taking API usability extremely seriously. Thus, we generally review every single API that is added to the product. This page discusses how we conduct API reviews for components that are open sourced.
+
+## Process Goals
+
+The key goals are:
+
+* **Designed for GitHub**. In order to be sustainable and not be a hurdle for contributors the API review process must feel natural to folks familiar with GitHub.
+
+* **Efficiency**. Performing API reviews requires looping in a set of experts. We want to conduct API reviews in an agile fashion without randomizing the reviewers or community members.
+
+* **Transparency**. We can use the same process for both internal as well as external contributors. This allows contributors to benefit from the results of API reviews even if the implementer isn't external.
+
+## Overall Process
+
+GitHub is generally based around the pull-request model. The idea is that contributors perform their changes in their own fork and submit a pull request against our repository.
+
+For trivial code changes, such as typo fixes, we want folks to directly submit a pull request rather than opening an issue. However, for bug fixes or feature work, we want contributors to first start a discussion by creating an issue.
+
+For work that involves adding new APIs we'd like the issue to contain what we call a *speclet*. The speclet should provide a rough sketch of how the APIs are intended to be used, with sample code that shows typical scenarios. The goal isn't to be complete but rather to illustrate the direction so that readers can judge whether the proposal is sound. Here is [a good example](https://github.com/dotnet/corefx/issues/271).
+
+![API Review Process](images/api-review-process.png)
+
+## Steps
+
+* **Contributor opens an issue**. The issue description should contain a speclet that represents a sketch of the new APIs, including samples on how the APIs are being used. The goal isn't to get a complete API list, but a good handle on how the new APIs would roughly look like and in what scenarios they are being used. Here is [a good example](https://github.com/dotnet/corefx/issues/271).
+
+* **Community discusses the proposal**. If changes are necessary, the contributor is encouraged to edit the issue description. This allows folks joining later to understand the most recent proposal. To avoid confusion, the contributor should maintain a tiny change log, like a bolded "Updates:" followed by a bullet point list of the updates that were being made.
+
+* **Issue is tagged as "Accepting PRs"**. Once the contributor and project owner agree on the overall shape and direction, the project owner tags the issue as "Accepting PRs". The contributor should indicate whether they will be providing the PR or only contributed the idea.
+
+* **Coding**. The contributor is implementing the APIs as discussed. Minor deviations are OK, but if during the implementation the design starts to take a major shift, the contributor is encouraged to go back to the issue and raise the concerns with the current proposal.
+
+* **Pull request is being created**. Once the contributor believes the implementation is ready for review, she creates a pull request, referencing the issue created in the first step. In order to call dips, you can also create the PR before it's completely ready. Use checkboxes to indicate which areas are still missing so that we know it's not ready for review yet. [Here is a good example](https://github.com/dotnet/corefx/pull/316). At this time, if any new API are being added to a type that has shipped in the full .NET Framework, submit the pull request to the *future* branch. See [Branching Guide](branching-guide.md).
+
+* **Pull request is being reviewed**. The community reviews the code for the pull request. The review should focus on the code changes and architecture - not the APIs themselves. Once at least two project owners give their OK, the PR is considered good to go.
+
+* **Pull is tagged as "Needs API Review"**. The project owner then marks the pull request as "Needs API Review".
+
+* **API review**. Using the information in the pull request we'll create an APIX file that constitutes the API delta. The API review board meets multiple times a week to review all PRs that are tagged as needing an API review.
+
+* **API review notes are being published**. After the review, we'll publish the notes in the [API Review repository](https://github.com/dotnet/apireviews). A good example is the [review of immutable collections](https://github.com/dotnet/apireviews/tree/master/2015-01-07-immutable).
+
+* **Pull request is updated with the results of the API Review**. Once the API review is complete, the project owner uploads the notes and API HTML diff, including all comments. The project owner also updates the PR accordingly, with either a call to action to address some concerns or a good to go indicator.
+
+* **Pull request is merged**. When there are no issues - or the issues were addressed by the contributor, the PR is merged.
+
+## API Design Guidelines
+
+The .NET design guidelines are captured in the famous book [Framework Design Guidelines](http://amazon.com/dp/0321545613) by Krzysztof Cwalina and Brad Abrams.
+
+A digest with the most important guidelines are available in our [developer wiki](Framework-Design-Guidelines-Digest). Long term, we'd like to publish the individual guidelines in standalone repo on which we can also accept PRs and -- more importantly for API reviews -- link to.
+
+## API Review Notes
+
+The API review notes are being published in [API Review repository](https://github.com/dotnet/apireviews).

Documentation/branching-guide.md

@@ -0,0 +1,26 @@
+Branching Guide
+===============
+
+We will have the following branches in the corefx repository:
+
+* **master**
+ * Where most development happens
+ * Submit your PRs here unless you are adding API to a type that exists in the full .NET Framework
+
+* **future**
+ * Landing place for fully API and code reviewed changes that are not to be part of the next upcoming release.
+ * Submit your PRs here if you're adding surface area to a type that has shipped in the full .NET Framework as we can no longer accept those changes and achieve our compatibility goal for the first release of .NET Core
+ * Takes regular merges from master
+ * Once we snap for the first release, we will merge future to master and delete future
+
+* **release/[name]**
+ * Release branches snapped from master. 
+ * Do not submit pull requests to these branches
+ * Fixes here do not flow to follow-up releases
+ * Generally, fixes after a snap needing to make it in to a release will go in to master and get cherry-picked to the release branch.
+
+* **dev/[name]** 
+ * Features (aka topics) under active development by more than one developer.
+ * Submit PRs here only if you've made prior arrangements to work on something in one of these branches.
+ * It is up to the developers creating these branches to decide what level of review is required
+ * These features will only ship if they are successfully pulled to master or future via the standard PR and API review process.

Documentation/breaking-change-definitions.md

@@ -0,0 +1,38 @@
+Breaking Change Definitions
+===========================
+
+Behavioral Change
+-----------------
+
+A behavioral change represents changes to the behavior of a member. A behavioral change may including throwing a new exception, adding or removing internal method calls, or alternating the way in which a return value is calculated. Behavioral changes can be the hardest type of change to categorize as acceptable or not - they can be severe in impact, or relatively innocuous.
+
+Binary Compatibility  
+--------------------
+
+Refers to the ability of existing consumers of an API to be able to use a newer version without recompilation. By definition, if an assembly's public signatures have been removed, or altered so that consumers cannot no longer access the same interface exposed by the assembly, the change is said to be a _binary incompatible change_.
+
+Source Compatibility
+--------------------
+
+Refers to the ability of existing consumers of an API to recompile against a newer version without any source changes. By definition, if a consumer needs to make changes to its code in order to for it build successfully against a newer version of an API, the change is said to be a _source incompatible change_.
+
+Design-Time Compatibility  
+-------------------------
+
+_Design-time compatibility_ refers to preserving the design-time experience across versions of Visual Studio and other design-time environments. This can involve details around the UI of the designer, but by far the most interesting design-time compatibility is project compatibility. A potential project (or solution), must be able to be opened, and used on a newer version of a designer.
+
+Backwards Compatibility  
+-----------------------
+
+_Backwards compatibility_ refers to the ability of an existing consumer of an API to run against, and behave in the same way against a newer version. By definition, if a consumer is not able to run, or behaves differently against the newer version of the API, then the API is said to be _backwards incompatible_. 
+
+Changes that affect backwards compatibility are strongly discouraged. All alternates should be actively considered, since developers will, by default, expect backwards compatibility in newer versions of an API.
+
+Forwards Compatibility  
+----------------------
+
+_Forwards compatibility_ is the exact reverse of backwards compatibility; it refers to the ability of an existing consumer of an API to run against, and behave in the way against a _older_ version. By definition, if a consumer is not able to run, or behaves differently against an older version of the API, then the API is said to be _forwards incompatible_.
+
+Changes that affect forwards compatibility are generally less pervasive, and there is not as stringent a demand to ensure that such changes are not introduced. Customers accept that a consumer which relies upon a newer API, may not function correctly against the older API.
+
+This document does not attempt to detail forwards incompatibilities.