Visual Studio Toolbox

5 Tips for Contributing to Microsoft Open Source Projects

Microsoft made .NET Core and other .NET Foundation projects open to community collaboration. Want to make a contribution? Read these tips first.

• By Terrence Dorsey
• 01/21/2015

Last November Microsoft announced it would open source .NET and release a free, full-featured Visual Studio Community 2013 edition. This followed open sourcing ASP.NET, the "Roslyn" .NET Compiler Platform, and a number of other projects earlier last year.

If this is somehow news -- and even if it's not -- you should definitely read S. Somasegar's announcement post, "Opening up Visual Studio and .NET to Every Developer, Any Application: .NET Server Core open source and cross platform, Visual Studio Community 2013 and preview of Visual Studio 2015 and .NET 2015," over on MSDN for a pretty good overview. Actually, that title is a pretty good overview by itself, but definitely dive into the article itself for some useful details about what's being open sourced and the timeline for code availability.

The important piece I'd like to take a closer look at today involves this passage from Soma's post:

"Over the next several months, we will be open sourcing the remainder of the .NET Core Runtime and .NET Core Framework. These projects will be released under the MIT open source license and we are also issuing an explicit patent promise to clarify user patent rights to .NET. Developers can begin engaging with the breadth of .NET open source projects today at github.com/Microsoft/dotnet. "

So what does this mean for you? What does it take to move .NET Core code into your own projects? And, more important, given the suddenly more open aspect of so many Microsoft products, what does it mean to contribute back to the .NET Core, ASP.NET and other community Microsoft projects?

Here are five tips for getting yourself engaged in this new, open Microsoft development culture in a manner that is most likely to get the best results.

1. Background Reading
One example of the way these projects affect the .NET development community comes from the Mono project, which plans to "bring the best pieces of .NET to Mono, and contribute the cross-platform components of Mono to the .NET efforts." (See Figure 1.) They got started right away, as celebrated in this tweet from Miguel de Icaza: "Another chunk of .NET source code replaces more Mono code."

For an overview about how open source .NET will impact Mono, take a look at de Icaza's "Microsoft Open Sources .NET and Mono" post, which he summed up succinctly: "Like we did in the past with .NET code that Microsoft open sourced, and like we did with Roslyn, we are going to be integrating this code into Mono and Xamarin's products." You'll find a more comprehensive explanation and specific details of the products that will use the .NET Core code in the Mono Project's own ".NET Source Code Integration" roadmap.

I also highly recommend reading Immo Landwerth's "Introducing .NET Core" post on the .NET Framework Blog. Landwerth, a program manager on the .NET team, explains the motivations for creating .NET Core, what it means for the future of .NET and C# programming on Microsoft platforms, and specific details about community .NET Core development.

2. Learn What's Available
As a potential contributor, your first stop should be the new Microsoft on GitHub portal (see Figure 2), your single source for finding all of the organizations Microsoft has set up for open source and community projects.

From this project portal, you can browse or search all of the available repositories that have been pushed to GitHub. There's also a list of just the .NET Foundation Projects on the .NET Foundation site itself, the .NET Foundation GitHub page and the .NET Foundation home repo README, so there's little chance of you not finding the right project link.

As I mentioned, there are hundreds of other repositories available from Microsoft, including tools, SDKs and examples, other than the .NET Foundation projects. These include projects like the Azure Documentation Center, the MusicStore app demonstrating ASP.NET MVC and Entity Framework, the Win2D API for immediate mode 2D graphics, and much more.

3. Read the Contribution Guidelines
Before you do anything else, take the time to read and become familiar with the General .NET Contributing Guide. This wiki document lays out in detail the expectations for any developer making changes or additions to Microsoft community projects. It starts with forking, branches and pull requests, then goes on to discuss coding style (with code examples), commit messages, and some rules of the road (dos and don'ts).

There's a Developer Guide, which covers the expected development environment and practices for contributors. You'll need to use Visual Studio 2013 Update 3 or later or the latest Visual Studio 2015 Preview. This includes Visual Studio Community 2013. You're also expected to have full code coverage for your contributions using xUnit.net.

You'll also want to take a look at the guidelines for compatibility and breaking changes. As a rule, you never want to contribute a breaking change. However, there are exceptions (and subtle edge cases) for nearly every rule. If your contribution may affect existing functionality in even a trivial manner, you'd be wise to start a discussion in the issues area for the repository, which I'll discuss soon.

The main contribution guide I linked to earlier is specifically for the CoreFX (.NET Core) project. Based on what I've been told, this guide applies generally to all of the .NET Foundation projects, and I think it would be good practice to apply them to any of the Microsoft projects you'll find on GitHub.

Some projects have their own contribution guidelines. A good example is the TypeScript repository. For better or worse, these guidelines are not always exactly the same from project to project, and may be documented in different ways. Before submitting a pull request, read the README.md file, check the wiki page and look for a "contributing" file in the repo first.

4. Follow Discussions About Issues
The first rule of .NET contributions is "Unless it is a trivial change, make sure that there is a corresponding issue for your change first. If there is none, create one." Not only are issues important for explaining the purpose of your change, they're also a key resource for understanding the development team's roadmap for the project and for identifying possible areas for individual contributions.

Over on the .NET Foundation Forum, I asked, "What does it mean to contribute?" Landwerth offered a few suggestions. His recommendation is to start with the issue tracker (also see Figure 3):

"This gives you an idea of what folks care about. You should also look at the issue tracker and look for open bugs to get a handle on the direction of the project. ... Most projects encourage folks to file an issue before starting to invest a lot of time into coding. This ensures that both parties can get on the same page to see whether that's the right direction for the project. It's also a good starting point for discussing design options."

Landwerth also suggests looking through the comments on previous pull requests. It gives you an idea of how you should organize and document your contributions to improve the chances that your pull request will be accepted.

Another way to find out what contributions are needed is to check the Up For Grabs site, which a number of open source projects are using to advertise their need for contributions. There are all sorts of projects here, so filter on the .NET tag to narrow down the results.

5. Read the .NET Foundation Forums
Another site you should frequent for guidance and discussion on .NET Core and related projects is the .NET Foundation Forums. The subjects covered here are more general and free-flowing than in the issue trackers for individual project repositories, but you'll also get a more general insight into the roadmap, guidelines for, and scope of development for all .NET Foundation projects.

When I set out to write this column, I turned to the .NET Foundation Forums to ask about best practices for community contributions. You can read the thread ".NET contributor 101: What does it mean to contribute?" and add questions to keep the discussion going. Gyuris Krisztian asked a similar question, specifically about contributing to Mono and Xamarin projects, , "I would like to help. How do I start?"

There are many other questions and discussions there, and certainly something related to your personal interests in .NET Foundation projects. One that's particularly relevant to me professionally is the "Documentation Conventions & Tooling?" thread started by Jonathan Pryor. Please read it because documentation is important. Really.

One thing to keep in mind as you read and contribute to these threads: These are early days for the .NET Foundation projects and for the latest generation of Microsoft open-source projects in general. In many cases, the direct answer to many questions boils down to something like, "We're still working out the details ..." This is not a great answer -- I'd hoped the teams had thought through the process a little better, particularly because open source isn't exactly a new thing, even at Microsoft. However, it's an honest answer, and it usually comes with guidance to follow until better standards and practices are worked out.

Be cool, go with the flow, and be a team player. If you have suggestions, share them. Move the conversation forward.

Making Your Contribution
You'll notice that a lot of these tips involve reading, watching and following. Take this to heart. If you want to succeed in being part of a community effort, don't expect that you'll be able to do your own thing all of the time. Remember, it's a community effort, and it's Microsoft's community.

Pay attention to what the community is talking about, follow the guidelines, be open to feedback. Then get your code on and contribute.

Good luck!