Microsoft’s Open Source Program

Microsoft has a strong open source program that encourages contribution, respects license obligations, and allows engineers to use open source with ease, work in the open, release projects, and be secure.

Our developers use more than 200,000 open source components every month while building products and services.

Relentless automation, engineering system innovation, and making it easy for our developers to "fall into the pit of success" have been key to using open source at enterprise-scale.

Here are just a few of the ways that we've built a strong open source program. We're sharing our process in hopes it helps others be more successful in open source too.

The Microsoft open source program is managed by the Open Source Programs Office in partnership with expert teams across Microsoft. A community of open source experts, open source leaders, and others help curate guidance and policy.

One Engineering System (1ES)

The 1ES team at Microsoft has made using, releasing and contributing to open source an easy, efficient, native part of the engineering experience.

Building on a foundation of eliminate (reducing complex and dated policies for the modern engineering era), automate (detecting open source use, automated policy and decision guides, legal alerts and security workflows), and delegate (letting business groups make decisions aligned with their priorities and goals), the open source program has scaled.

Built into the engineering system: Powered by GitHub and Azure Pipelines, and internal hyperscale CloudBuild, CloudTest, and policy systems, many tasks as simple as maintaining an inventory of the open source used in builds and products is automatic.
Using GitHub Enterprise Cloud: Over 60,000 engineers at Microsoft are using GitHub Enterprise Cloud to host and release official Microsoft open source projects, samples, and documentation, building communities and connecting directly with technologists and Microsoft customers right on GitHub, working in the open.

Expert support & resources

A coalition of teams, experts, and friendly resources are available to make sure that everyone at Microsoft understands how to use open source.

Easy, crisp guidance for engineers: Comprehensive reference material for everyone at Microsoft to refer to helps to share knowledge and reduce confusion. Checklists, policies and advanced guides have been prepared by Subject Matter Experts, open source attorneys, and curated by engineers, to make learning about using open source easy and efficient.

If you work at Microsoft, you can authenticate and find these resources at aka.ms/opensource.
Open Source Standards and Legal Team: Expert attorneys and program managers with decades of open source experience from across the industry make up the legal team that crafts policies, guidance, and inform their clients regarding all their licensing and open community needs. Every employee at Microsoft has access to an open source attorney dedicated to their organization and familiar with their business goals and unique needs.
Open Source Champs: Internal e-mail discussion lists and Microsoft Teams channels make it easy and straightforward to connect with open source maintainers and experts to get answers.

The Open Source Champs come from teams across Microsoft and are able to help advise their team and help share knowledge.
Business and Legal review process: Some open source activities at the company, depending on use case, license, or other conditions, may automatically trigger a straightforward business and legal review process.

An open source review takes the form of a standard engineering work item and presents reviewers with a contextual look at the business goals, specific use scenario, and other aspects, to help make the right decisions for some scenarios.
Open Source Executive Council: Essentially the board of directors for the open source program, the executive council consists of leaders from across Microsoft. The council helps to guide the program, highlight opportunities, and provide a central place for decisions regarding open source.

OpenChain 2.1 conformance

Trust is key to open source. Developers should be able to trust users to respect their licensing choices. And when you receive software, you should be able to trust that the open source licenses were followed.

The OpenChain Project plays an important role in building trust by setting standards that define how to operate a high-quality open source compliance program. It means that when you receive open source from a company that follows the OpenChain standard, you can be assured that the code went through a rigorous license compliance process. You can trust it.

We announced that Microsoft is OpenChain 2.0-conformant in December 2019 and continue to keep the program up-to-date, most recently self-certifying OpenChain 2.1 requirements.

Tools & Services

Microsoft uses many tools and services in supporting its open source program. Here are just a few that you may find useful in your own company or open source community.

GitHub Enterprise Cloud with SAML single-sign on

Microsoft has over 70 GitHub organizations dedicated to open source activities. Collectively, these are part of an enterprise account at GitHub.

Some of the features the enterprise product brings to us include:

SAML single sign-on adds an additional layer of protection for Microsoft by connecting with Microsoft's Azure Active Directory system, verifying access and protecting access tokens and SSH keys.
Secure supply chain features such as private repo secret scanning help to discover accidental check-in of credentials, while vulnerability notifications and built-in dependency update pull request capabilities help projects to stay in the best shape.

GitHub Actions and Azure Pipelines

While Microsoft uses many different continuous integration systems, and open source projects adopt whatever common toolset an open source community prefers, many projects are powered by GitHub Actions and Azure Pipelines.

GitHub Actions are the preferred way for projects to build and validate. Being built-in to the GitHub experience for developers, configuration is quick and easy.
Azure Pipelines can be exposed to public, open communities, allowing many Microsoft projects to continue using the build system they've been using for many years, but with a collaborative angle.

Component Governance

At Microsoft, a internal extension for Azure DevOps called Component Governance was created to help provide automatic inventory of all the open source components used.

Automatic inventory registration: every build at Microsoft is connected to Component Governance. Detected open source is registered, enabling teams to trace a specific build to the bill of materials it contained, and providing historical snapshots and build-by-build analysis of change. The automatic inventory is connected to an alerting system and business review system as needed.
Security alerts: by connecting to security data sources, public known vulnerability data such as CVEs, and curated Microsoft-internal security knowledge, alerts can be raised at any time to help engineers protect Microsoft and its customers.
Legal alerts: open source license data and algorithms specific to Microsoft's open source approach are used to generate alerts when specific components have additional legal obligations or requirements, such as publishing third-party source disclosures to https://3rdpartycode.microsoft.com/.
Business review process: a legal and business review process, implemented as Azure Boards work items, is used for certain uses of open source.

GitHub Bots

Many different bots and applications are used as part of Microsoft's open source program. Bots help teams to scale and provide a great experience for communities.

Some of the common building blocks for GitHub Bots used at Microsoft include:

Probot framework for building GitHub Apps to automate and improve your workflow
octokit/rest.js REST API client for JavaScript and Node.js apps to connect to GitHub
Octokit.net for .NET applications to integrate with GitHub

Self-service GitHub open source portal

When interfacing with third-party services such as GitHub, it is important to be able to identify employees at the same company working together on open source.

While GitHub allows organization members to publicize their organization membership on their individual profile, there is more to know. GitHub user management solutions will offer the following capabilities:

Employment lifecycle automation: Employees should be able to join a company organization, if authorized, without needing a manual invitation. When an employee decides to leave the company, their access to company resources and GitHub organization membership should be removed.
User linking: Authenticating an employee with IT and also GitHub to associate the GitHub account
Communications: By linking an employee's corporate identity with their GitHub account, comms are possible without having to ask the user to share their email address or other information on their public profile.

Microsoft's self-service GitHub management portal is implemented in TypeScript and is a Node.js service. The portal is open source at https://github.com/microsoft/opensource-portal.

ClearlyDefined

ClearlyDefined provides license, source location, and attribution information on over 10 million open source components. We rely on this data for our compliance systems.

This open source project provides compliance data about open source components from across the package ecosystems. It uses multiple open source scanners and summarizes their results into a high-quality "definition" of the component upon which we base our business policy decisions internally. It also:

Enables crowd-sourced curations: In cases where the data about a component is missing or incomplete, the project facilitates community curation of the data in order to improve it. This process is all done transparently and with multiple community reviewers.
Facilitates data improvements upstream: Over time, the corpus of ClearlyDefined curations are intended to be submitted back to the upstream projects as pull requests so that future versions of the component are more clearly defined.

ClearlyDefined is an open source project of the Open Source Initiative (OSI) and its open source code is at https://github.com/clearlydefined.

Microsoft's Contributor License Agreement (CLA)

The Microsoft's Contributor License Agreement is a Contributor License Agreement solution that integrates nicely with GitHub to make sure that all contributors to a project have agreed to common terms by enabling contributors to sign CLAs from within a pull request.

GitHub data crawling

Microsoft has developed and adopted several different approaches to retrieving GitHub data about activity within our organizations: we use the GitHub REST API v3 and GraphQL to regularly make data about our GitHub repos, traffic data, issues and pull requests all available inside our big data systems.

By making data available in Azure Data Explorer, powered by Kusto, it's really quick for Microsoft engineers to be able to query data without having to build specialized GitHub API integrations.

Microsoft's 1ES team is in the process of open sourcing this technology.

Business review process with Azure Boards

Our business and legal review process - kicked off when a particular open source use, contribution, or release, scenario requires - integrates into the engineering system that includes Azure Boards. This helps meet engineers where they are, providing an easy way to review requirements, manage approvals and workflow, and eventually completing any necessary reviews.

This system is built by using the Work Item Tracking extensibility features and the Azure DevOps REST API.

Open source use guidance

This is a summary of how we approach using open source at Microsoft.

Using open source in Microsoft is encouraged. Building on the efforts of others allows us to create meaningful value for our customers faster and engage with new ecosystems and user-bases in a natural way.

Take the following steps to use an open source component at Microsoft:

Register All Open Source: Following the open source compliance policy, all open source components must be registered. You can do this two ways:
- One Engineering System automatically registers most types of open source. Open source detectors are run and will handle the registration of open source components. Legal and security alerts will be raised with follow-up actions if there is additional work required, such as meeting legal obligations, posting to the third-party disclosures site, addressing a security issue, or if a commercial or unknown license is present.
- For repos using certain types of open source, a Manual Registration approach or file can be used in lieu of detectors. Boutique engineering systems will need to refer to the non-standard build environments content.
Distribution Requirements: If you plan on distributing the open source component in a Microsoft Product or Service, you must take additional steps, as guided by legal alerts, that might include NOTICE file generation and making source code available.

Contributing to open source

This is a summary of how we approach contributing to open source at Microsoft.

We encourage our employees to contribute to open source communities. Contributing improvements to projects we use enhances the value everyone derives from the project and can drive a project forward.

Microsoft's contribution policy varies depending on the size and purpose of contribution.

Small changes: If your contribution meets the "Small Contribution Exception", just create a fork, make the fix, and submit a pull request. If making the pull request on GitHub, you can create the fork in your personal GitHub account, rather than an official corporate organization account.
Larger changes: If the contribution is larger, your contribution should be reviewed and approved. There is a contribution request form that will kick of a business and legal review process, how to scope the request. The process will include reviewing the contributor guide and the CLA for the project.
Meet Community On Its Own Terms: Note that different open source communities take contributions in different ways. Before firing off a pull request, investigate how best to engage the community you will be contributing back to.
Fork Nicely: Always try to contribute to a community instead of hard forking. Review internal guidelines and training before forking into an official GitHub org.

Working in the open

Teams at Microsoft are encouraged to work in the open and are provided with straightforward guidance on when and how to release code to the world.

This is a summary of how we approach releasing open source at Microsoft.

Approval process

All open sourcing of Microsoft source code and content (e.g., text, images, fonts, data) must be registered with your business and legal team using the workflow outlined in the release documentation.

In other cases, you may need to work with your management and legal teams to review the business case, success plan, and IP management strategy around your proposal.

Location

All Microsoft open source code should be released on GitHub in one of Microsoft's GitHub orgs. The vast majority of projects will go in the official company org.

Where we are participating in existing community that does not work on GitHub, your code should go in the natural location for that community.

If you do not plan on releasing your code to the public, an InnerSource location provided by the One Engineering System team is a better option for private engineering work: for example, using Azure Repos.

Licensing

Microsoft open source code should be released under the MIT license absent a compelling reason to do otherwise.

Contributions

All contributions to a Microsoft-managed open source project must use the Microsoft Contributor License Agreement (CLA). The CLA must be agreed to by all contributors who are not Microsoft Full-time Employees (FTE) or interns prior to the contribution being merged into the project codebase.

The CLA requirement is waived in certain smaller contribution cases.

Release checklist

The following steps should be taken to release and maintain your open source project:

Create your repo and register your release: The "new repo wizard" contains a form of questions regarding your release. Start there, or, if you created the repo directly on GitHub, you'll receive a link by e-mail to complete the wizard and unlock your repo.

If a business and legal review is needed, the wizard will trigger that review process at the end.
Include the following in your repo root directory. The default template may have placed these files for you as a start:
- A README.md file describing the purpose and state of the repository, with a link to the Microsoft Open Source Code of Conduct and a description of any third-party code included in the repository. A good README file is often critical to project success.
- A LICENSE file with an OSI approved license text.
- A CONTRIBUTING.md file with instructions on contributing to the project that must include at least the minimum required information. That minimum information includes that contributions to Microsoft projects are subject to our Contributor License Agreement. Additionally, consider providing technical guidance like build instructions, coding conventions, or a project roadmap in the CONTRIBUTING.md file.
Prepare the code for release:
- Code license: Include the language-appropriate license comment at the head of each source file.
- Remove sensitive assets:
  - Remove any reference in the code to internal or confidential information, including internal paths, tools, codenames, proprietary fonts, internal telemetry and email aliases.
  - Prepare the code and commit history for publication, including running certain internal corporate tools for this purpose.
- Third-party Open Source: If your repository includes third-party OSS, describe its use and its license in a NOTICE file. Your open source attorney team may have additional details on this process for you.
Publish the code: Once your registration and review process is complete, make your GitHub repository public using the Settings pane on GitHub.
Going forward: Ensure:
- Further Microsoft Contributions: You must file a contribution request if either the feature you are adding is outside the scope of your original release request OR you are adding non-open source Microsoft code that your team did not author.
- Staffing: Ensure at least one team member is committed to managing community interactions merging pull requests, giving feedback, releasing new versions.
- Buildable & Runnable: Make sure that your project is easy to build and has binaries available is key to attracting contributors.
- Foster your community: Look for ways to continue engagement with potential contributors.

Our program