This project is read-only.

Contributing Code

Before submitting a feature or substantial code contribution please discuss it with the team and ensure it follows the product roadmap. The team rigorously reviews and tests all code submissions. The submissions must meet an extremely high bar for quality, design, and roadmap appropriateness.

For now, the team has set the following limits on pull requests:
  • Contributions beyond the level of a bug fix must be discussed with the team first, or they will likely be declined. As our process matures and our experience grows, the team expects to take larger contributions.
  • Only contributions against the master branch or the branch that corresponds to the latest Preview release of VS 2015 will be accepted. Authors submitting pull requests that target experimental feature branches or release branches will be asked target their pull request at master or the branch corresponding to the latest preview release of VS 2015 instead.
  • Pull requests that do not merge easily with the tip of the master branch will be declined. The author will be asked to merge with tip and submit a new pull request.
  • Submissions must meet functional and performance expectations, including scenarios for which the team doesn’t yet have open source tests. This means you may be asked to fix and resubmit your pull request against a new open test case if it fails one of these tests.
When you are ready to proceed with making a change, get set up to build the code and familiarize yourself with our workflow and our coding conventions. 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.

You must sign a Contributor License Agreement (CLA) before submitting your pull request. To complete the CLA, submit a request via the form and electronically sign the CLA when you receive the email containing the link to the document. You need to complete the CLA only once to cover all Microsoft Open Technologies OSS projects.

Developer Workflow

  1. Work item is assigned to a developer during the triage process
  2. Microsoft Open Tech developers do local work in a branch; external contributors do local work in a fork. Please use rebase to keep the tree clean and without unnecessary merge operations. Pulling and rebasing frequently will help reduce the chances of merge conflicts.
  3. Microsoft Open Tech developers will use the internal code review systems; external contributors should push their fork to the server and issue a pull request to initiate the code review process.
  4. When the code review process is complete and a change is accepted, a team member will push the changes to the master branch.

Creating New Issues

Please follow these guidelines when creating new issues in the issue tracker:
  • 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 not set any bug fields other than Impact.
  • Specify a detailed description of the issue or requested feature.
  • For bug reports, please also:
    • 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.
  • Subscribe to notifications for the created issue in case there are any follow up questions.

Triage Process

The team uses the following workflow to triage bugs in the issue tracker:
  1. New issues are opened in the Proposed state.
  2. New issues are triaged and moved from the Proposed to Active state in the event that the triage team feels a change or deeper investigation is warranted. The triage team aspires to triage the issues daily.
  3. When developers begin work on issues, they assign the bugs to themselves.
  4. When the changes for issues are committed to master or the investigations have concluded, the developers add their findings to the issues, change the statuses to Resolved, and assign the issues to the individuals that opened them.

Coding Conventions

  • Use plain code to validate parameters at public boundaries. Do not use Contracts or magic helpers.
    if (argument == null)
    {
        throw new ArgumentNullException("argument");
    }
  • Use Debug.Assert() for checks not needed in retail 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”.
  • 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.
  • Do not use tab characters in source files. Standard indentation levels use 4 spaces. In Visual Studio, you can 'untabify' a source document from the Edit|Advanced menu. You can also enable the "View White Space" option from the Edit|Advanced to make sure you are using the right settings.
  • Interface names should be prefixed with an “I”, e.g.: ISomeInterface.
  • Types, methods, properties, constants, events, and public fields should use Pascal-casing, e.g. ThisIsAPascalCaseName.

Formatting

In general, please use the formatting style of the code surrounding your change. The team does not follow these guidelines 100% of the time, but the team does follow them predominantly.

C#

  • The team uses the BSD/Allman style, as defined on this site: http://en.wikipedia.org/wiki/Indent_style. The brace associated with a control statement sits on the next line, indented to the same level as the control statement. Statements within the braces are indented to the next level.
    void Method(int x)
    {
        if (x == 1)
        {
            DoSomething();
        }
        else
        {
            DoSomethingElse();
        }
    }
  • Use braces to denote a block even when they are unnecessary as in the ‘if’ statement above.
  • Use spaces around binary operators except the member access operators: ‘.’ and ‘->’
  • Use camel case for locals, parameters, and non-public fields, e.g., thisIsACamelCaseName.
  • Use named parameters to give clarity to what a parameter means when passing a literal, but do not use named parameters to pass parameters in a different order than the method declaration.
  • Don't use ‘var’ in situations in which the type is not mentioned on the right hand side of the declaration. Examples of where ‘var’ is appropriate:
    • Creation expressions: var f = new Foo();
    • Casts: var f = (Bar)b;
    • Use of the well-known extension method 'Cast': var f = b.Cast<Bar>();
    • "as" expressions: var f = d as SomeType;

Visual Basic

For all of the C# guidelines which have analogs in Visual Basic, the team applies the spirit of the guideline to Visual Basic. Guidelines surrounding spacing, indentation, parameter names, and the use of named parameters are all generally applicable to Visual Basic. ‘Dim’ statements should also follow the guidelines for the use of ‘var’ in C#. Specific to Visual Basic, field names should begin with ‘m_’ or ‘_’. And the team prefers that all field declarations be placed at the beginning of a type definition. The Visual Studio members dropdown does not show fields in VB. Having them at the beginning of the type aids in navigation.

Last edited Dec 10, 2014 at 3:29 AM by KevinRansom, version 19