. NET Core Open Source Update

. NET Core Open Source updaterate This
Immo Landwerth [MSFT]Jan 11:39 AM

• 20

Wow. Just Wow. I don ' t know of a better to describe my feelings right now. Open source is probably one of the most energizing projects our team have been working on. It ' s been a blast so far and the stream of enthusiastic contributors and interactions doesn ' t seem to stop any time soon.

In this post, I want to give you a long overdue update on where we is, interesting changes we made, and give an overview of what ' s coming next. Read to the end, this is a post for you don ' t want to miss.

A good problem to have:too many forks to display

In the first update to open source I hinted at the fact that we've several teams at Microsoft whose focus are on collecting Telemetry. The reason we invest so much and this space are due to the shift from many-year release cycles to quasi real-time delivery. For services, continuous deployment is a very common paradigm today. As a result, the industry have come up with various tools and metrics to measure the health of services. Why are this necessary? Because you need to know when a problem was about to happen, wasn't when it already happened. You want the small adjustments over time instead of drastic changes every once in a while because it's much less risky .

Open source is no different from that perspective. We want to know how do we ' re doing and somewhat predict how this might change over time by recognizing trends. It's interesting to point out of the the metrics aren ' t used by management to evaluate my team or even individuals. We Use the metrics to evaluate ourselves. (In fact, I believe this evaluating engineers with metrics was a game you can ' t win–engineers be smart little buggers th At always find a through to game the system).

One metric totally made my day. When browsing the graphs of the Corefx repo, GitHub displays the following:

Indeed we ' ve more than forks! Of course, this a total vanity metric and not indicative of the true number of engagements we have. But we ' re still totally humbled by the massive amount of interest, we see from the community. And we ' re also a tiny bit proud.

But the total number of pulling requests is pretty high. In total, we ' re approaching to requests since last November(which includes both, contributors from Communit Y as well as Microsoft):

(In case you wonder, I also has a hypothesis what the plateau means).

We ' re also thrilled to learn, we ' re already outnumbered by the community:the number of community contributions are hig Her than the number of contributions from us. That's the reason why open source scales so well–the Community acts as a strong multiplication force.

Real-time communication

One of the reasons why we decided to open source. NET Core is the ability to build and leverage a stronger ecosystem. Specifically, this was what I wrote last year:

To us, open sourcing the stack also means we ' re able to engage with customers in real-time. Of course, not every customer wants interact with us that closely. The ones who does make the stack better for all of us because they provide us with early & steady feedback.

Of course, the real-time aspect cuts both ways. It ' s great if we hear from real-time. But how is we responding? If you ever filed a bug in Connect, you may not have had the impression that real-time are a concept that the people outsid E of the Skype organization has heard of. No offense to my fellow microsofties; I ' M guilty too. It ' s incredibly difficult to respond in a timely manner if the worlds of the product team and their active customers is s Eparated by several years.

In order to understand how responsive we is, we collect these the metrics:

• How quickly does we respond to an issue? This was the time it takes us to add the first comment.

• How quickly does we close an issue? This is the time it takes us to close a issue, regardless of whether it was addressed or discarded.

Here is the graphs:

So far these look pretty good, and is in the realm of real-time collaboration. But there is also some-improvement:getting a first response shouldn ' t take more than a week. We'll try to improve in the this area.

Open Development process

Part of the reason I share these metrics are to underline so we ' re fully committed to an open development process.

But establishing an open development process was more than just sharing metrics and writing blog posts. It's about rethinking the engineering process for a open source world. In a Channel 9 interview we said so we want to is mindful of the new opportunities that open source brings and not Simpl Y expose our existing engineering and processes. The reason isn ' t much that we fear giving anything away; It's about realizing, we existing processes were geared for multi-year release cycles, so isn't all of the them make sense For open source and agile delivery. In order to get there, we generally want to start with less process and only add if it ' s necessary.

This requires adapting existing processes and adding some new processes. Let me give you a quick update of which processes we currently has and what tweaks we made.

Code Reviews

To me, this was by far the most valuable part of collaborative software engineering. Realizing how many mistakes you can prevent by just letting somebody else see your code is a very liberating experience. It ' s also the easiest-spread knowledge across the team. If you haven ' t do code reviews, you should start immediately. Once You do them, you'll ever go back, I promise.

If you're on our GitHub pull requests, you'll find that they aren ' t just from the COMMUNITY–WE also leverage pull requ ESTs for performing our code reviews. In fact, for parts of the. NET Core is already on GitHub, there is no internal code reviews–all code reviews full Y happen on GitHub with public.

This have many advantages:

• sharing expectations. You can understand "what feedback we" re providing our peers with, and hence expect contributors to follow, too.

• Community participation. Anybody can comment on we pull requests which enables both, you and us, to benefit from the feedback of the entire commun ity.

• Our pull request metric looks better. Just kidding. A nice side effect of the using pull requests for code reviews are that everything are in one place. There is, tooling wise, no difference between me code reviewing my coworker's code and reviewing a community pull request. In other words, doing code reviews on public makes our lives easier, not harder.

API Reviews

My team spends a lot of time on API design. This includes making sure a API is very usable, leverages established patterns, can being meaningfully versioned, and is com Patible with the previous version.

The "we ' ve approached API design is as follows:

• Guidance. We ' ve documented what constitutes good. NET API design. This information are available publicly as well, via the excellent book Framework Design guidelines, written by our Archite CT Krzysztof Cwalina. A Super-tiny Digest is available on our wiki.

• StaticAnalysis. We ' ve invested into static analysis (formerly known as FXCOP) to find common violations, such as incorrect naming or not F Ollowing established patterns.

• API reviews . On top of this, a Board of API review experts reviews every single API. We usually don ' t do the daily basis, because that wouldn ' t efficient. Instead, we review the general API design once a prototype or proposal are available by the team building the API. Depending on the complexity we sometimes review additional iterations. For example, we reviewed the Roslyn APIs many, many times because the number of APIs and concepts are quite large.

We ' ve found this process to be invaluable because the guidelines themselves is also evolving. For example, when we add new language features and patterns it's important to come up with a set of good practices that EV Entually get codified into guidelines. However, it ' s rare that the correct guidelines is known at day one; In the most cases guidelines is formed based on experience. It's super helpful to has a somewhat smaller group that's involved in a large number of APIs reviews because this focuses The attention and allows those folks to discover similarities and patterns.

With the open source, we thought how we can incorporate API reviews to an open development process. We ' vepublished a proposal on GitHub and based in your feedback put into production. The current API review process are nowdocumented on our wiki.

But have a documented process is just one piece of the puzzle. As many of pointed out, it's a huge burden if the reviews is black boxes. After all, the point of the have an open development process are to empower the community to being successful with contributing Features. This requires infusing the community with the tribal knowledge we have. To does this, we started to record the reviews and upload them to Channel 9. We also upload detailed notes and link them to the corresponding parts in the video.

Of course, a complex topic like API design isn ' t something so one can learn by simply watching a review. However, watching these reviews would give you a good handle on what aspects we ' re looking for and how we approach the prob Lem space.

We ' ve also started to document some less documented areas, such as breaking changes and performance considerations for the BCL. Neither page claims to is complete but we ' re curious to get your feedback.

Contributor license agreements (CLAs)

Another change we recently did is requiring contributors to sign a Contributor license Agreement (CLA). You can find a copy of the CLA on the. NET Foundation. The basic idea is making sure, all code contributed to projects in the. NET Foundation can be distributed under their respective licenses.

This is what CLAs is exposed to you:

1. You submit a pull request

2. We ' ve an automated system to check if the change requires a CLA. F or example, trivial typo fixes usually don ' t require a CLA. If no CLA is required and the pull request was labelled as  cla-not-required  and you ' re-done.

3. If The change requires a CLA, the system checks whether you already signed one. If you do, then the pull request is labelled as  cla-signed  and your ' re done.

4. If You need to sign a CLA, the bot would label the request as  cla-required  and post a COM ment pointing the CLA (fully electronic, no faxing involved) from the Web site to sign. Once signed a CLA, the pull request is labelled as  cla-signed  and you ' re-done.

Moving forward, we'll only accept pulling requests that is labelled as either cla-not-required or cla-signed.

It ' s worth pointing out, that we intend to has a single CLA for the entire. NET Foundation. So once your signed a CLA for any project in the. NET Foundation, you ' re-done. This means, for example, if you signed a, the CLA as part of the a pull request for Corefx, and you won ' t has to sign another the CLA for Roslyn.

Automated CI System

We ' ve always had an automated build system. The triggers varies between teams, but the most common approach are a daily build in conjunction with a gate that performs Some validation before any changes go. For the open source world, have an internal build system isn ' t helping much.

The most common practice on GitHub are to use a continuous integration (CI) system that builds on every push, including PUL L requests. This is the reviewers on the pull requests don ' t has to guess whether the change would pass the build or not–the Registere D CI System simply updates the PR accordingly.

GitHub itself doesn ' t provide a CI system, it relies on 3rd parties to provide one. Originally, we used Appveyor. It's free to open source projects and I use it on all my personal projects now. If you haven ' t, I highly recommend checking them out. Unfortunately, Appveyor currently only supports building on Windows. In order to enable our cross-platform work we wanted a system, the We can run other systems, especially Linux. So we went ahead and now host our own Jenkins servers to perform the CI service.

We ' re still learning

Our team is still learning and we believe it's best to being transparent about it. As David Kean said in our initial open source interview:

Don ' t be afraid to call us on it. If We do something wrong, overstep us boundaries, or does something that you thing we should has done better On it.

The earlier can tell us, the better. So why isn't share our thinking and learning before we do decisions based on it? Here is a few examples.

• Bots talking to Bots . When we own CI system and added the CLA process, we got a bit trigger happy with using bots, which is started Essentially automated systems posting comments. This resulted in a flood of comments which caused a lot of noise in the PR discussions and some cases even dominated th E Number of comments. Nobody on our side quite liked it, but we also didn ' t think it is the end of the world. But then one customer said:  "I am losing a little bit interest because are hard-to-track real things going on". Statements like this is helpful because they make us aware of potential problems. We quickly realized that the number of folks annoyed are actually quite high so we prioritized this work and made our bots A lot less chatty. Instead of C3PO, we now have R2D2. No chitchatting, but few, short and actionable comments.

• Using Git . The most we team members has a lot of experience with using centralized version control, especially team Foundation Versi On Control (TFVC). While we also has a set of quite experienced Git users, our team as a whole are still adapting to a decentralized workflow , including usage of topic branches and flowing code between many remotes. Andrew Arnott, who some of your probably know from The channel 9 interview on immutable collections, recently did a Gi T training for the. NET team. We recorded it and uploaded it to Channel 9. We ' d love to hear from if sharing these kind of videos are interesting to you!

• up-for-grabs. There is an established pattern in the open source community to mark issues in a specific how that the community can query For if they want to find opportunities We ' ve started to label issues with Up-for-grabs to indicate bugs or features that we believe is easy to get started with And we don ' t currently plan on tackling ourselves. Thanks to Brendan Forster, the COREFX project are now also listed on Up-for-grabs.net, which are a website devoted to Docume NT on what open source projects ask the community for support. Based on some questions Brandon raised, this also started a discussion of what up-for-grabs actually means. Feel free to jump in and let us know what are you think!

Is there any and topics you ' d interested in? Let us know!

Library availability

At the time of the Connect () event, we have had a fraction of the libraries available on GitHub:

• System.Collections.Immutable
• System.Numerics.Vectors
• System.Reflection.Metadata
• System.Xml

Those four libraries totaled about 145k lines of code. Since then, we ' ve added many more libraries which more than tripledthe code size to now more than half a mill Ion lines of code:

• Microsoft.Win32.Primitives
• Microsoft.Win32.Registry
• System.Collections.Concurrent
• System.Collections.Immutable
• System.Collections.NonGeneric
• System.Collections.Specialized
• System.Console
• System.Diagnostics.FileVersionInfo
• System.Diagnostics.Process
• System.IO.FileSystem
• System.IO.FileSystem.DriveInfo
• System.IO.Pipes
• System.IO.UnmanagedMemoryStream
• System.Linq.Parallel
• System.Numerics.Vectors
• System.Reflection.Metadata
• System.Text.RegularExpressions
• System.Threading.Tasks.Dataflow
• System.Xml

And we ' re not even do yet. In fact, we've only tackled about 25% 's to come for. NET Core. A full list was available in an Excel spread sheet.

Summary

Since November, we ' ve made several improvements towards an open development model. Code reviews is in the open and so is API reviews. And–best of All–we ' ve a very active community which already outnumbers the contributions from our team. We couldn ' t has hoped for more.

Nonetheless, we ' re still at the beginning for our open source journey. We ' re heads-down with bringing more. NET Core libraries onto GitHub. On top of this, the runtime team is busy getting the CoreCLR repository ready. You can expect a update on this topic quite soon.

As always, we ' d love hearing guys think! Let us know via the comments, by posting to. NET Foundation Forums or by tweeting @dotnet.

netcore_opensourceupdate.xlsx

. NET Core Open Source Update