diff --git a/Documentation/README.md b/Documentation/README.md index 1a3906b96913..22fe6ef69a50 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -12,13 +12,13 @@ Getting Started =============== - [Installing the .NET Core SDK](https://www.microsoft.com/net/core) -- [[WIP] Official .NET Core Docs](http://dotnet.github.io/docs/) +- [Official .NET Core Docs](https://docs.microsoft.com/dotnet/core/) Project Docs ============ +- [Project Roadmap](https://github.com/dotnet/core/blob/master/roadmap.md) - [Developer Guide](project-docs/developer-guide.md) -- [Project priorities](project-docs/project-priorities.md) - [Contributing to .NET Core](project-docs/contributing.md) - [Contributing Workflow](project-docs/contributing-workflow.md) - [Performance Guidelines](project-docs/performance-guidelines.md) diff --git a/Documentation/project-docs/contributing-workflow.md b/Documentation/project-docs/contributing-workflow.md index 3634802a1084..8f18aae1693e 100644 --- a/Documentation/project-docs/contributing-workflow.md +++ b/Documentation/project-docs/contributing-workflow.md @@ -3,82 +3,7 @@ Contribution Workflow You can contribute to .NET Core with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated. -Getting Started -=============== - -If you are looking at getting your feet wet with some simple (but still beneficial) changes, check out _up for grabs_ issues on the [CoreCLR](https://github.com/dotnet/coreclr/labels/up-for-grabs) and [CoreFX](https://github.com/dotnet/corefx/labels/up-for-grabs) repos. - -For new ideas, please always start with an issue before starting development of an implementation. See [project priorities](project-priorities.md) to understand the Microsoft team's approach to engagement on general improvements to the product. Use [CODE_OWNERS.TXT](https://github.com/dotnet/coreclr/blob/master/CODE_OWNERS.TXT) to find relevant maintainers and @ mention them to ask for feedback on your issue. - -You do not need to file an issue for trivial changes (e.g. typo fixes). Just create a PR for those changes. - -Making a change -=============== - -Make a quality change. Consider and document (preferably with tests) as many usage scenarios as you can to ensure that your change will work correctly in the miriad of ways it might get used. - -There are several issues to keep in mind when making a change. - -Managed Code Compatibility --------------------------- -Please review [Breaking Changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) before making changes to managed code. Please pay the most attention to changes that affect the [Public Contract](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract). - -Typos ------ -Typos are embarrassing! We will accept most PRs that fix typos. In order to make it easier to review your PR, please focus on a given component with your fixes or on one type of typo across the entire repository. If it's going to take >30 mins to review your PR, then we will probably ask you to chunk it up. - -Coding Style Changes --------------------- - -We intend to bring dotnet/corefx in to full conformance with the style guidelines described in [Coding Style](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md). We plan to do that with tooling, in a holistic way. In the meantime, please: - -* **DO NOT** send PRs for style changes. -* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines. - -Commit Messages ---------------- - -Please format commit messages as follows (based on this [excellent post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)): - -``` -Summarize change in 50 characters or less - -Provide more detail after the first line. Leave one blank line below the -summary and wrap all lines at 72 characters or less. - -If the change fixes an issue, leave another blank line after the final -paragraph and indicate which issue is fixed in the specific format -below. - -Fix #42 -``` - -Also do your best to factor commits appropriately, i.e not too large with unrelated -things in the same commit, and not too small with the same small change applied N -times in N different commits. If there was some accidental reformatting or whitespace -changes during the course of your commits, please rebase them away before submitting -the PR. - -PR - CI Process -=============== - -The [dotnet continuous integration](http://ci.dot.net/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean. - -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. - -There is currently minimal test coverage for Linux and OS X builds that can be used by the dotnet CI. We are working to improve that so that more issues can be caught in CI, as is the case with Windows. - -PR Feedback -=========== - -Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback. - -1 or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me". - -There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback. - -Suggested Workflow -================== +## Suggested Workflow We use and recommend the following workflow: @@ -105,3 +30,19 @@ We use and recommend the following workflow: Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged. Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment. + +## PR - CI Process + +The [dotnet continuous integration](http://ci.dot.net/) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean. + +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. + +There is currently minimal test coverage for Linux and OS X builds that can be used by the dotnet CI. We are working to improve that so that more issues can be caught in CI, as is the case with Windows. + +## PR Feedback + +Microsoft team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback. + +1 or more Microsoft team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me". + +There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback. diff --git a/Documentation/project-docs/contributing.md b/Documentation/project-docs/contributing.md index 3bedc82b07c3..f0adffacc32a 100644 --- a/Documentation/project-docs/contributing.md +++ b/Documentation/project-docs/contributing.md @@ -1,59 +1,38 @@ Contributing to .NET Core ========================= -The .NET Core team maintains several guidelines for contributing to the .NET Core repos, which are provided below. Many of these are straightforward, while others may seem subjective. A .NET Core team member will be happy to explain why a guideline is defined as it is. +The .NET Core team maintains guidelines for contributing to the .NET Core repos. A .NET Core team member will be happy to explain why a guideline is defined as it is. -Contribution Guidelines -======================= +General contribution guidance is included in this document. Additional guidance is defined in the documents linked below. -- [Copyright](#copyright) describes the licensing practices for the project. -- [General Contribution Guidance](#general-contribution-guidance) describes general contribution guidance, including more subjective stylistic guidelines. -- [Contribution Bar](#contribution-bar) describes the bar that the team uses to accept changes. +- [Copyright](copyright.md) describes the licensing practices for the project. - [Contribution Workflow](contributing-workflow.md) describes the workflow that the team uses for considering and accepting changes. - [Garbage Collection Guidelines](garbage-collector-guidelines.md) for changes that affect the GC. - [Performance Guidelines](performance-guidelines.md) for changes in performance critical code or that otherwise affect performance. - [Porting the JIT](https://github.com/dotnet/coreclr/pull/2214#issuecomment-161850464) to other chip architectures. -General Contribution Guidance -============================= +Up for Grabs +------------ -There are several issues to keep in mind when making a change. +The team marks the most straightforward issues as "up for grabs". This set of issues is the place to start if you are interested in contributing but new to the codebase. -Managed Code Compatibility --------------------------- -Please review [Breaking Changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) before making changes to managed code. Please pay the most attention to changes that affect the [Public Contract](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract). +- [dotnet/corefx - "up for grabs"](https://github.com/dotnet/corefx/labels/up-for-grabs) +- [dotnet/coreclr - "up for grabs"](https://github.com/dotnet/coreclr/labels/up-for-grabs) -Typos ------ -Typos are embarrassing! We will accept most PRs that fix typos. In order to make it easier to review your PR, please focus on a given component with your fixes or on one type of typo across the entire repository. If it's going to take >30 mins to review your PR, then we will probably ask you to chunk it up. - -Commit Messages ---------------- - -Please format commit messages as follows (based on this [excellent post](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)): +Contribution "Bar" +------------------ -``` -Summarize change in 50 characters or less +Project maintainers will merge changes that improve the product significantly and broadly and that align with the [.NET Core roadmap](https://github.com/dotnet/core/blob/master/roadmap.md). -Provide more detail after the first line. Leave one blank line below the -summary and wrap all lines at 72 characters or less. +Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The .NET Core codebase is used by several Microsoft products (for example, ASP.NET Core, .NET Framework 4.x, Windows Universal Apps) to enable execution of managed code. Other companies are building products on top of .NET Core, too. We may revert changes if they are found to be breaking. -If the change fixes an issue, leave another blank line after the final -paragraph and indicate which issue is fixed in the specific format -below. - -Fix #42 -``` - -Also do your best to factor commits appropriately, i.e not too large with unrelated -things in the same commit, and not too small with the same small change applied N -times in N different commits. If there was some accidental reformatting or whitespace -changes during the course of your commits, please rebase them away before submitting -the PR. +Contributions must also satisfy the other published guidelines defined in this document. DOs and DON'Ts -------------- +Please do: + * **DO** follow our [coding style](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md) (C# code-specific) * **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines. * **DO** include tests when adding new features. When fixing bugs, start with @@ -62,7 +41,9 @@ DOs and DON'Ts it's often better to create new issue than to side track the discussion. * **DO** blog and tweet (or whatever) about your contributions, frequently! -* **DO NOT** send PRs for style changes. +Please do not: + +* **DON'T** make PRs for style changes. * **DON'T** surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time. @@ -70,19 +51,10 @@ DOs and DON'Ts * **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it. * **DON'T** add API additions without filing an issue and discussing with us first. See [API Review Process](https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md). -Contribution "Bar" -================== - -Project maintainers will merge changes that align with [project priorities](project-priorities.md) and/or improve the product significantly for a broad set of apps. Proposals must also satisfy the published [guidelines for .NET Core](#contribution-guidelines). - -Maintainers will not merge changes that have narrowly-defined benefits, due to compatibility risk. The CoreCLR codebase is used by several Microsoft products (e.g. Windows Phone, ASP.NET Core, .NET Framework 4.x) to enable execution of managed code. Changes to the open source codebase can become part of these products, but are first reviewed and tested to ensure they are correct for those products and will not inadvertently break applications. We may revert changes if they are found to be breaking. - -Contributing Ports ------------------- - -We encourage ports of CoreCLR to other platforms. Linux and OS X ports are in progress and have a lot of momentum behind them. There is also interest in a [FreeBSD port](https://github.com/dotnet/coreclr/issues/455) (and OpenBSD and NetBSD). +Managed Code Compatibility +-------------------------- -Ports have a weaker contribution bar, since they do not contribute to compatibility risk with existing Microsoft products on Windows. For ports, we are primarily looking for functionally correct implementations. +Contributions must maintain [API signature](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract) and behavioral compatibility. Contributions that include [breaking changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) will be rejected. Please file an issue to discuss your idea or change if you believe that it may affect managed code compatibility. Contributing to mscorlib library -------------------------------- @@ -94,28 +66,34 @@ Most managed code changes should be made in the [CoreFX](https://github.com/dotn - The type exists in CoreCLR only -> choose CoreCLR. - In doubt -> choose CoreFX. -Please see [Breaking Changes](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md) to understand our requirements on changes that could impact compatibility. Please pay the most attention to changes that affect the [Public Contract](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/breaking-changes.md#bucket-1-public-contract). We will not accept changes that break compatibility. +Commit Messages +--------------- + +Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)): + +``` +Summarize change in 50 characters or less -Copyright -========= +Provide more detail after the first line. Leave one blank line below the +summary and wrap all lines at 72 characters or less. -The .NET Core copyright is held by ".NET Foundation and Contributors". See [.NET Foundation](http://www.dotnetfoundation.org/). +If the change fixes an issue, leave another blank line after the final +paragraph and indicate which issue is fixed in the specific format +below. -Source License --------------- +Fix #42 +``` -The .NET Core project uses multiple licenses for the various project repositories. Most projects use the [MIT License](https://opensource.org/licenses/MIT) for code and the [Creative Commons Attribution 4.0 International Public License (CC-BY)](https://creativecommons.org/licenses/by/4.0/) license for documentation. The [Apache 2 License](https://opensource.org/licenses/Apache-2.0) is also used. +Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits. -See the license file at the root of project repositories for the specific license, such as with the following examples: +Contributor License Agreement +----------------------------- -- [CoreCLR](https://github.com/dotnet/coreclr/blob/master/LICENSE.TXT) [(MIT)](https://opensource.org/licenses/MIT). -- [Roslyn](https://github.com/dotnet/roslyn/blob/master/License.txt) [(Apache 2)](https://opensource.org/licenses/Apache-2.0). -- [core-docs](https://github.com/dotnet/core-docs/blob/master/license.txt) [(CC-BY)](https://creativecommons.org/licenses/by/4.0/). +You must sign a [.NET Foundation Contribution License Agreement (CLA)](http://cla2.dotnetfoundation.org) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. -Binary License --------------- +The agreement: [net-foundation-contribution-license-agreement.pdf](https://cla2.dotnetfoundation.org/cladoc/net-foundation-contribution-license-agreement.pdf) -Microsoft produces a distribution of .NET Core licensed under the [.NET Library License](https://www.microsoft.com/net/dotnet_library_license.htm). Other groups or companies may produce their own distributions of .NET Core. +You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (for example, you just fixed a typo), then the PR is labelled with `cla-not-required`. Otherwise it's classified as `cla-required`. Once you signed a CLA, the current and all future pull-requests will be labelled as `cla-signed`. File Headers ------------ @@ -131,6 +109,28 @@ The following file header is the used for .NET Core. Please use it for new files - See [class.cpp](../../src/vm/class.cpp) for an example of the header in a C++ file. - See [List.cs](../../src/mscorlib/src/System/Collections/Generic/List.cs) for an example of the header in a C# file. +Contributing Ports +------------------ + +We encourage ports of CoreCLR to other platforms. There are multiple ports ongoing at any one time. You may be interested in one of the following ports: + +Chips: + +- [ARM32](https://github.com/dotnet/coreclr/labels/arch-arm32) +- [ARM64](https://github.com/dotnet/coreclr/labels/arch-arm64) +- [X86](https://github.com/dotnet/coreclr/labels/arch-x86) + +Operating System: + +- [Linux](https://github.com/dotnet/coreclr/labels/os-linux) +- [macOS](https://github.com/dotnet/coreclr/labels/os-mac-os-x) +- [Windows Subsystem for Linux](https://github.com/dotnet/coreclr/labels/os-windows-wsl) +- [FreeBSD](https://github.com/dotnet/coreclr/labels/os-freebsd) + +Note: Add links to install instructions for each of these ports. + +Ports have a weaker contribution bar, at least initially. A functionally correct implementation is considered an important first goal. Performance, reliability and compatibility are all important concerns after that. + Copying Files from Other Projects --------------------------------- @@ -150,17 +150,3 @@ Porting Files from Other Projects There are many good algorithms implemented in other languages that would benefit the .NET Core project. The rules for porting a Java file to C# , for example, are the same as would be used for copying the same file, as described above. [Clean-room](https://en.wikipedia.org/wiki/Clean_room_design) implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea. - -Contributor License Agreement ------------------------------ - -You must sign a [.NET Foundation Contribution License Agreement (CLA)](http://cla2.dotnetfoundation.org) before your PR will be merged. This is a one-time requirement for projects in the .NET Foundation. You can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. - -The agreement: [net-foundation-contribution-license-agreement.pdf](https://cla2.dotnetfoundation.org/cladoc/net-foundation-contribution-license-agreement.pdf) - -You don't have to do this up-front. You can simply clone, fork, and submit your pull-request as usual. When your pull-request is created, it is classified by a CLA bot. If the change is trivial (e.g. you just fixed a typo), then the PR is labelled with `cla-not-required`. Otherwise it's classified as `cla-required`. Once you signed a CLA, the current and all future pull-requests will be labelled as `cla-signed`. - -Patents -======= - -Microsoft has issued a [Patent Promise for .NET Libraries and Runtime Components](https://github.com/dotnet/coreclr/blob/master/PATENTS.TXT). diff --git a/Documentation/project-docs/copyright.md b/Documentation/project-docs/copyright.md new file mode 100644 index 000000000000..d51a2410d404 --- /dev/null +++ b/Documentation/project-docs/copyright.md @@ -0,0 +1,34 @@ +Copyright +========= + +The .NET Core copyright is held by ".NET Foundation and Contributors". + +The [.NET Foundation](http://www.dotnetfoundation.org/) is an independent organization that encourages open development and collaboration around the .NET ecosystem. + +Source License +-------------- + +The .NET Core project uses multiple licenses for the various project repositories. + +- The [MIT License](https://opensource.org/licenses/MIT) is used by most repositories for [code](https://github.com/dotnet/coreclr/). +- The [Apache 2 License](https://opensource.org/licenses/Apache-2.0) is also used by some projects for [code](https://github.com/dotnet/roslyn/). +- The [Creative Commons Attribution 4.0 International Public License (CC-BY)](https://creativecommons.org/licenses/by/4.0/) license is used for [documentation](https://github.com/dotnet/docs/) and [swag](https://github.com/dotnet/swag). + +Binary License +-------------- + +.NET Core distributions are licensed with a variety of licenses, dependent on the content. By default, the MIT license is used, the exact same as the [source license](https://github.com/dotnet/core/blob/master/LICENSE.TXT), with the same copyright holder. There are some cases where that isn't possible because a given component includes a proprietary Microsoft binary. This is typically only the case for Windows distributions. + +The following rules are used for determining the binary license: + +- .NET Core binary distributions (zips, nuget packages, …) are licensed as MIT (identical to the [.NET Core source license](https://github.com/dotnet/core/blob/master/LICENSE.TXT)). +- The license link (if there is one) should point to the repository where the file came from, for example: https://github.com/dotnet/corefx/blob/master/LICENSE.TXT. +- If the contained binaries are built from multiple .NET Core repositories, the license should point to dotnet/core: https://github.com/dotnet/core/blob/master/LICENSE. +- If the contents are not 100% open source, the distribution should be licensed with the .NET Library license: `https://www.microsoft.com/net/dotnet_library_license.htm`. +- It is OK for licensing to be asymmetric for a single distribution type. For example, it’s possible that the .NET Core SDK distribution might be fully open source for Linux but include a closed-source component on Windows. In this case, the SDK would be licensed as MIT on Linux and use the .NET Library License on Windows. It is better to have more open licenses than less. +- It is OK for the source and binary licenses not to match. For example, the source might be Apache 2 but ships as an MIT binary The third party notices file should capture the Apache 2 license. This only works for a permissive licenses, however, we have limited the project to that class of licenses already. The value of this approach is that binary licenses are uniform. + +Patents +------- + +Microsoft has issued a [Patent Promise for .NET Libraries and Runtime Components](https://github.com/dotnet/coreclr/blob/master/PATENTS.TXT). diff --git a/Documentation/project-docs/project-priorities.md b/Documentation/project-docs/project-priorities.md deleted file mode 100644 index bb49427227db..000000000000 --- a/Documentation/project-docs/project-priorities.md +++ /dev/null @@ -1,27 +0,0 @@ -.NET Core Goals and Priorities -============================== - -Microsoft published .NET Core to GitHub, with the following goals and priorities. - -Goals ------ - -- 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)). - -Priorities ----------- - -The project has the following priorities, set by the .NET Team: - -- 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. - -Microsoft Team Engagement -------------------------- - -The Microsoft team will engage on incoming PRs and issues that align with these goals and priorities. The team will also try to engage on other issues as time allows. - -The community is encouraged to create a broad range of issues. There may be a significant group of developers that are interested in the same topic. If a strong community viewpoint establishes itself on an issue outside of the core priority, then the team will likely engage on the issue. Engagement does not mean that the Microsoft team will necessarily build a feature, but discuss merits and implementation approaches.