dotnet/designs is where a .NET feature has to earn its place

A proposal queue for the runtime, framework and SDK

dotnet/designs is not a library and there is nothing to install. Its own description is one line: this repo is used for reviewing new .NET designs. The documents inside are design proposals for the .NET platform, and the value of the repository lies in the writing rather than in any build output.

The scope is deliberately bounded. The repository focuses on designs for the runtime, the framework and the SDK. Anything about the C# language itself is a different conversation handled in dotnet/csharplang, VB in dotnet/vblang, and F# across the fsharp/fslang-design and fsharp/fslang-suggestions repositories. That separation is stated in the README rather than left to be discovered, and it saves a lot of misdirected issues for anyone new to .NET governance.

So who is this for? The README is blunt about it: unless you are driving the design of a feature, you are not expected to contribute to this repo. The people who read these documents are the .NET runtime, library and tooling maintainers who have to agree on a shape before code gets written, plus the contributors whose work depends on that agreement.

accepted and proposed are the two states that matter

The top level of the repository is a document tree, and the folder names carry the workflow. There is an accepted folder, a proposed folder, a meta folder and a tools folder, alongside INDEX.md, CONTRIBUTING.md, SECURITY.md, CODE-OF-CONDUCT.md, a.markdownlint.json configuration and an.editorconfig.

The distinction between accepted and proposed is the core of the model. A document in accepted is a decision that has been merged; a document in proposed is still a proposal that has not been agreed. The meta folder holds the process paperwork, including meta/proposals.md, which the README links as the set of design proposals, and meta/template.md, which is the starting point for a new one.

Reading the tree tells you something about how a platform like.NET is actually governed. The record is public and versioned alongside the code. Anyone who wants to know why a particular API shape exists can look for the design document that argued for it, and anyone who wants to change it can see the format the argument has to take. The tools folder and the update-index script at the root are the small amount of automation that keeps that index honest.

The licence field on the repository says Other, because GitHub cannot classify the notice, and the README states the terms plainly: the project is licensed with the Creative Commons BY 4.0 License. That is a documentation licence rather than a software licence, which fits a repository whose payload is prose.

update-index is the one command a contributor runs

Creating a proposal follows a five step sequence, and the mechanical part of it is small. The steps are to create a new branch off of main, to create a document in the accepted folder starting from meta/template.md, to run ./update-index to regenerate INDEX.md, to open a pull request against main, and to merge once broad agreement is reached.

The index update is the only command involved.

./update-index

For Windows users the root also carries update-index.cmd, which is the same step expressed as a batch script rather than a shell entry point. There is a .vscode/ directory, so the repository assumes an editor that will read the editorconfig and the markdownlint rules, and the .github/ directory holds the workflow configuration for the pull request process.

What you should see after running the command is a modified INDEX.md that lists the new document. The README points readers to INDEX.md as the complete listing of proposals, and the script exists so that a contributor does not have to hand-edit a table that is easy to get out of date. Anyone reading the repository can therefore treat INDEX.md as the map and the accepted folder as the content.

The pull request is where the real work happens

The step that cannot be scripted is step five. The README says a pull request is merged once broad agreement is reached, and that phrase does a lot of work. There is no mechanical acceptance criterion, no test that passes, and no bot that will tell you a design is good.

For a reader, this is the most interesting property of the repository and also its biggest weakness in a review cycle. A merged document is the outcome of an argument between people who have to implement it, maintain it and document it for years. That is exactly why the accepted folder is worth reading, and exactly why a proposal that arrives without prior discussion tends to take a long time.

There is a related practical point about where requests go. The README says that if you merely want to request new features you should file an issue for the corresponding repo, and it links to the .NET core documentation page that maps repositories to their areas. So the flow for an ordinary user is an issue on a product repository, and the flow for a design contributor is a proposal document here, opened as a pull request after the index is regenerated.

The security and conduct files at the root round out the governance surface, and the .NET Foundation project statement places the repository inside a formal foundation structure rather than a single company's own process.

Design documents are not a substitute for the shipped API

The honest limitation of this repository is that a proposal is a plan, not a guarantee, and it is not a substitute for reading the actual shipped code. The records here capture intent, the trade-offs considered and the shape that was agreed. What actually exists in a given .NET release is defined by the implementation, and the two can diverge in timing: a design may be accepted long before a feature reaches a shipped preview, or an implementation may diverge from the document in small ways as the API is refined.

The same caution applies to the split with the language repositories. A design in dotnet/designs may depend on a C# language feature that lives in dotnet/csharplang, so reading one without the other gives an incomplete picture. And because this repository has no GitHub releases, there is no version history of the proposals themselves to page through. The only dating available comes from the commits, and the last push to the repository was on 2026-10-07.

For a team deciding whether to adopt a platform feature, the useful move is to read the accepted document, then read the shipped reference documentation for the API, and treat a difference between the two as a question rather than a defect.

How this compares with the language design repositories

The closest alternative to a proposal repository is a design document written somewhere else, or a blog post and a pull request with no record. The difference in approach is where the decision lives and who can find it later.

The.NET Foundation splits design work by layer, and each split has its own repository. dotnet/designs covers the runtime, framework and SDK, which is the layer where a change is a matter of platform engineering rather than language syntax. dotnet/csharplang covers C# language designs and suggestions, dotnet/vblang covers VB, and the F# work is split across fsharp/fslang-design for designs and fsharp/fslang-suggestions for suggestions. The distinction between designs and suggestions in the F# naming is itself a signal of how these repositories sort proposals by how settled they are.

A second alternative is to skip the written proposal entirely and open a pull request against the implementation. That works when the change is small and uncontroversial, and it is faster. It fails when the change alters public API surface, because then there is no durable record of why the shape was chosen, and the next person to touch that area has nothing to read. The proposal repositories exist to close that gap, and the accepted folders are effectively the platform's long term design memory.

Editorial conclusion

Adopt the practice of dotnet/designs, not the code, if you are designing a change to the runtime, framework or SDK, because a merged proposal is the record of the decision and its alternatives. Do not file a feature request there, since the repository states that ordinary requests belong in an issue on the corresponding repo, and it also excludes C#, VB and F# language design, which live in dotnet/csharplang, dotnet/vblang and the F# design repositories. Before opening a pull request, copy meta/template.md into the accepted folder, run ./update-index so INDEX.md lists the new document, and expect the review to stall until broad agreement is reached.

Frequently asked questions

Official sources

1. dotnet/designs on GitHub
2. Issues
3. README