Microsoft's default repo templates

The official, default template at Microsoft is the one called mit. If you combine the files in the shared/ folder with the files in projections/mit, you get the standard, default set of files that new GitHub repos are placed with in the company.

These files are packaged as the default, standard recommended content for net new GitHub repos created by Microsoft teams across all official Microsoft GitHub orgs such as microsoft, MicrosoftDocs, Azure, etc.

This is not a GitHub repo template, however, since we have a number of different orgs. Previous to 2020, this content was partially mirrored in the microsoft.github.io repo.

When Microsoft teams create new repos, either through internal tooling, or on GitHub directly, these files are applied as sane defaults and help to encourage community.

Please help build the future of Microsoft open communities by making thoughtful contributions here.

These projects should be technology-agnostic.

There are several templates Microsoft uses at this time, partly for historical reasons, and also because there are different legal entities - some projects are copyright Microsoft Corporation, while others are for the .NET Foundation.

The templates today are listed below. The official, main, primary Microsoft template is called "mit":

Sample projects intended for the legacy GitHub org azure-samples use this template. The README.md file has a boilerplate set of headings to help people get started. The repo also has a robust CONTRIBUTING.md file with guidance on issues, features, etc.

Contoso is the Microsoft entity used for "fake demo companies, etc.". The Contoso template is used by Microsoft's open source engineering system for validating the template system, but never used by actual product teams.

Repos that consist primarily of documentation content that are intended for .NET Foundation projects use this template. The template consists of a LICENSE covering docs, a LICENSE-CODE file covering any code samples, and the README.md file has some additional language about trademarks in a Legal Notices section.

The standard default template for .NET Foundation projects that Microsoft teams may be helping work on and release. Similar to the mit license.

An "issue-only" repo is a GitHub repository that primarily is used to report bugs, issues, and other feedback, but not host or store code.

Default template for docs-related repos that are used by the Microsoft Learn site.

The standard, default template for Microsoft releases, placing an MIT LICENSE file and other basics such as a SECURITY.MD file.

Official samples that are indexed at Microsoft Learn's code samples and also are copyright-assigned to the .NET Foundation use this template.

The README.md file has a rich metadata header with required fields and information that is processed by the docs site. The template outlines some of the files that are placed.

Samples created through this mechanism are also configured automatically with a GitHub webhook that connects with a sample publishing system.

Official samples that are indexed at Microsoft Learn's code samples.

The README.md file has a rich metadata header with required fields and information that is processed by the docs site. The template outlines some of the files that are placed.

Samples created through this mechanism are also configured automatically with a GitHub webhook that connects with a sample publishing system.

For some reason, we once thought that having an "other" template made sense. It may be a good time to remove it.

The common directory contains defaults that all templates use unless overridden.

These are more specific templates for projects such as Microsoft official samples or .NET Foundation projects.

// psuedo-code
for (each templateName of projections) {
  copy(sharedFiles, excludingAnySpecialExclusions);
  copy(specificProjectionFiles);
}

This project welcomes contributions and suggestions.

Pull requests to this repo will be reviewed, at a minimum, by the Open Source Programs Office at Microsoft, as well as a set of Microsoft's "Open Source Champs", for guidance.

Please understand that these templates often need to be kept rather simple, since they are a starting point, and if there is too much guidance, teams may not be familiar with how to react and manage projects with too much initial content.

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.