Contributing to the .NET Core repository

The .NET Core project has been developed and is now being maintained in an open source fashion on GitHub. However, just like every project, there are some coding rules and a code of conduct that you must follow in order to be a one of the “good citizens.” In this chapter, we will cover the coding guidelines that you must follow if you want to contribute to the project.

PR guidelines

The team, at some point in time, will re-style the complete codebase of the project according to the coding guidelines (which we’ll we talk about later in this chapter). In the meantime, you should:

• NOT send PRs for style changes. For example, do not send PRs renaming all the occurrences of Int32 to int.
• NOT send PRs for upgrading code to use newer language features. Those features can be used in new code, but for the existing code, it is a whole new thing.
• GIVE priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
• NOT submit to the master branch API additions to any type that has shipped in the full .NET framework. And in addition, do not submit PR to the APIs that have not yet been approved.
• INCLUDE tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
• KEEP the discussions focused.
• NOT surprise the team with big pull requests. Instead, file an issue and start a discussion so that the team can help you with your developments.
• NOT commit code that you didn't write. If you find code that you think is a good fit to add to .NET Core, file an issue and start a discussion before proceeding.
• NOT submit PRs that alter licensing-related files or headers.

Coding guidelines: C#, C++, and general code files

The general rule is to follow Visual Studio defaults. However, there are some more detailed cases. For C++ files (*.cpp and *.h), you should use clang-format (version 3.6+). After changing any C++ or H file and before merging, run the shell script located in src/Native/format-code.sh; this script will ensure that all native code files adhere to the coding style guidelines.

For non-code files (.xml, etc.) there is no specific rule, but in general, you should privilege consistency with what is already written. When editing files, keep new code and changes consistent with the style in the files. In case of new files, you should keep following the conventions used in the other files of the same type. Last, but not least: use good judgment. If a component is new, be sure to use what is broadly perceived as appropriate in that situation.

The official coding guideline rules

Using the official project documentation available on GitHub as a source, here’s the full list of guidelines that you should follow:

1. We use Allman style braces, where each brace begins on a new line. A single line statement block can go without braces, but the block must be properly indented on its own line and it must not be nested in other statement blocks that use braces (See issue 381 for examples).
2. We use four spaces of indentation (no tabs).
3. We use _camelCase for internal and private fields, and use readonly where possible. Prefix instance fields with _, static fields with s_, and thread static fields with t_. When used on static fields, readonly should come after static (i.e. static readonly not readonly static).
4. We avoid this. unless absolutely necessary.
5. We always specify the visibility, even if it's the default (i.e. private string _foo not string _foo). Visibility should be the first modifier (i.e. public abstract not abstract public).
6. Namespace imports should be specified at the top of the file, outside of namespace declarations, and should be sorted alphabetically.
7. Avoid more than one empty line at any time. For example, do not have two blank lines between members of a type.
8. Avoid spurious free spaces. For example, avoid if (someVar == 0)..., where the dots mark the spurious free spaces. Consider enabling "View White Space (Ctrl+E, S)" if using Visual Studio, to aid detection.
9. If a file happens to differ in style from these guidelines (e.g., private members are named m_member rather than _member), the existing style in that file takes precedence.
10. We only use var when it's obvious what the variable type is (i.e. var stream = new FileStream(...) not var stream = OpenStandardInput()).
11. We use language keywords instead of BCL types (i.e. int, string, float instead of Int32, String, Single, etc.) for both type references as well as method calls (i.e. int.Parse instead of Int32.Parse).
12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop.
13. We use nameof(...) instead of "..." whenever possible and relevant.

If you believe that following these rules will be hard, don’t worry—the team has provided a .vssettings file to automatically set up Visual Studio formatting correctly. The file is located at the root of the corefx repo. Moreover, there is a Roslyn-based tool that you can use to check the “health” of your code. The tool is called CodeFormatter, and it’s actively used inside the project. It is available here.

Licensing

In open source projects, licensing is the key. The MIT license is mainly used by.NET Core, but Microsoft produces a distribution of .NET Core licensed with the .NET Library license. The .NET Core repo may also contain sources licensed differently, the team outlines them in third-party notices whenever needed. .NET Core binaries are produced and licensed separately.