Skip to content

Latest commit

 

History

History
56 lines (40 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

56 lines (40 loc) · 4.23 KB
Raw

Contributing to Roslyn

Guidelines for contributing to the Roslyn repo.

Submitting Pull Requests

  • DO ensure submissions pass all Azure DevOps legs and are merge conflict free.
  • DO follow the .editorconfig settings for each directory.
  • DO submit language feature requests as issues in the C# language / VB language repos. Once a feature is championed and validated by LDM, a developer will be assigned to help begin a prototype on this repo inside a feature branch.
  • DO NOT submit language features as PRs to this repo first, or they will likely be declined.
  • DO submit issues for other features. This facilitates discussion of a feature separately from its implementation, and increases the acceptance rates for pull requests.
  • DO NOT submit large code formatting changes without discussing with the team first.

When you are ready to proceed with making a change, get set up to build (either on Windows or on Unix) the code and familiarize yourself with our developer workflow.

These two blogs posts on contributing code to open source projects are good too: Open Source Contribution Etiquette by Miguel de Icaza and Don’t “Push” Your Pull Requests by Ilya Grigorik.

Creating Issues

  • DO use a descriptive title that identifies the issue to be addressed or the requested feature. For example, when describing an issue where the compiler is not behaving as expected, write your bug title in terms of what the compiler should do rather than what it is doing – “C# compiler should report CS1234 when Xyz is used in Abcd.”
  • DO specify a detailed description of the issue or requested feature.
  • DO provide the following for bug reports
    • Describe the expected behavior and the actual behavior. If it is not self-evident such as in the case of a crash, provide an explanation for why the expected behavior is expected.
    • Provide example code that reproduces the issue.
    • Specify any relevant exception messages and stack traces.
  • DO subscribe to notifications for the created issue in case there are any follow up questions.

Coding Style

The Roslyn project is a member of the .NET Foundation and follows the same developer guide. The repo also includes .editorconfig files to help enforce this convention. Contributors should ensure they follow these guidelines when making submissions.

CSharp

  • DO use the coding style outlined in the .NET Runtime Coding Guidelines
  • DO use plain code to validate parameters at public boundaries. Do not use Contracts or magic helpers.
if (argument == null)
{
    throw new ArgumentNullException(nameof(argument));
}
  • DO use Debug.Assert() for checks not needed in release builds. Always include a “message” string in your assert to identify failure conditions. Add assertions to document assumptions on non-local program state or parameter values, e.g. “At this point in parsing the scanner should have been advanced to a ‘.’ token by the caller”.
  • DO avoid allocations in compiler hot paths:
    • Avoid LINQ.
    • Avoid using foreach over collections that do not have a struct enumerator.
    • Consider using an object pool. There are many usages of object pools in the compiler to see an example.

Visual Basic Conventions

  • DO apply the spirit of C# guidelines to Visual Basic when there are natural analogs.
  • DO place all field declarations at the beginning of a type definition

Tips 'n' Tricks

Our team finds using this enhanced source view of Roslyn helpful when developing.