Understanding the Docs Directory in ASP.NET Core: A Complete Contributor Guide

The docs directory in the dotnet/aspnetcore repository serves as the central, version-controlled knowledge base for contributor-focused documentation, containing internal guides for building, testing, and modifying the framework rather than end-user API references.

The dotnet/aspnetcore repository powers one of the most widely used web frameworks in the .NET ecosystem, spanning thousands of projects across multiple submodules. Unlike the public documentation hosted at docs.asp.net, the docs folder at the repository root maintains internal contributor documentation that evolves in lock-step with the source code. This ensures that anyone cloning the repository has immediate access to the exact procedures required to build from source, navigate governance processes, and service the shared framework runtime.

What Is the Docs Directory in ASP.NET Core?

The docs directory functions as a self-contained knowledge base targeting developers who contribute to the ASP.NET Core framework itself. Located at the root of the repository, it houses markdown files, process diagrams, and configuration guides that address the complexities of working with a massive codebase.

According to the repository structure, docs/README.md acts as the primary entry point, outlining every document in the folder and describing what each one covers. This approach keeps critical contributor information under version control, ensuring that instructions for building the codebase or submitting API changes remain synchronized with the current state of the main branch.

Key Documents for Contributors

Build and Development Setup

docs/BuildFromSource.md provides step-by-step instructions for setting up a local development environment on any operating system. This document explains how to use the repository's restore scripts to install dependencies such as the .NET SDK and Node.js packages.

# Clone the repository including submodules

git clone --recursive https://github.com/dotnet/aspnetcore.git
cd aspnetcore

# Run the restore script as documented in BuildFromSource.md

./restore.sh        # Linux/macOS

./restore.cmd       # Windows PowerShell

The build documentation also references solution filters (.slnf) and helper scripts like startvs and startvscode to open specific project areas efficiently.

API Governance and Review Processes

docs/APIReviewProcess.md defines the strict governance model for proposing or changing public APIs within the framework. This document outlines the required PR prefixes, review templates, and approval workflows that maintain backward compatibility and design consistency.

Additional process documents include:

• IssueManagementPolicies.md – Defines how issues are triaged and categorized.
• TriageProcess.md – Details the weekly triage procedures used by the maintainers.

Servicing and Patch Management

docs/Servicing.md establishes the workflow for back-porting fixes and managing patch updates across supported release branches. Contributors working on critical fixes reference this alongside PreparingPatchUpdates.md to ensure proper targeting of servicing branches.

docs/SharedFramework.md explains the architecture and policy governing the shared framework runtime, including how runtime components are packaged and distributed.

Versioning and Infrastructure

docs/UpdatingMajorVersionAndTFM.md contains the exhaustive checklist for bumping the major version number and updating the target framework moniker (TFM) during release cycles. This includes updating assembly versions, branch configurations, and compatibility baselines.

docs/Submodules.md provides critical guidance for working with the repository's Git submodules, while Helix.md documents the Helix test infrastructure used for continuous integration across multiple platforms.

Diagnostics and Tooling

docs/list-of-diagnostics.md maintains a catalog of diagnostic IDs (such as ASP0005) used by analyzers throughout the codebase. When adding new compiler warnings or analyzers, contributors consult this file to reserve the next available ID.

# Check for the next available diagnostic ID

grep -n "ASP000" docs/list-of-diagnostics.md

docs/tooling-consolidation.md explains how the repository's build tooling and project systems are organized, helping contributors understand the relationship between MSBuild targets and repository-level scripts.

Practical Workflow Examples

Building a Specific Project Area

After running the initial restore, contributors can build isolated sections of the repository using area-specific scripts documented in the build guides:

cd src/Http               # Navigate to the Http abstractions area

./build.sh                # Build only this project

./build.sh -test          # Run associated unit tests

Preparing for API Changes

Before submitting a PR that modifies public surface area, contributors must follow the checklist in APIReviewProcess.md:

# Review the API review requirements

code docs/APIReviewProcess.md

# Ensure your branch includes the required documentation updates

# and that PR titles follow the specified prefix convention

Working with Submodules

For changes that cross repository boundaries, the docs provide specific Git commands:

# Update submodules as described in Submodules.md

git submodule update --init --recursive

Summary

The docs directory in dotnet/aspnetcore functions as the authoritative source for contributor operations:

• docs/README.md serves as the central index for all contributor documentation.
• BuildFromSource.md enables reliable cross-platform development environment setup.
• Process documents like APIReviewProcess.md and Servicing.md enforce quality and consistency across contributions.
• Infrastructure guides for Helix, submodules, and diagnostics simplify navigation of the complex build system.
• Version-controlled storage ensures documentation remains synchronized with code changes.

Frequently Asked Questions

Is the docs directory the same as the official ASP.NET Core documentation?

No. The docs directory contains internal contributor documentation for building and modifying the framework itself. The official API reference and tutorials for developers using ASP.NET Core are published at docs.asp.net and maintained in separate repositories. Files like docs/BuildFromSource.md assume you are compiling the framework from the dotnet/aspnetcore repository rather than consuming it as a NuGet package.

How do I set up a local build environment using the repository docs?

Begin by reading docs/BuildFromSource.md and running the appropriate restore script for your platform (./restore.sh on Linux/macOS or ./restore.cmd on Windows). These scripts install the required .NET SDK, Node.js dependencies, and native tooling. After restoration, use the area-specific build.sh or build.cmd scripts in subdirectories like src/Http to compile individual components rather than the entire repository.

What is the API review process documented in the repository?

The API review process, defined in docs/APIReviewProcess.md, requires that any public API changes undergo formal review before merging. Contributors must fill out a review template, use specific PR title prefixes, and obtain approval from the API review board. This process ensures that new APIs follow consistent naming conventions, maintain backward compatibility, and align with the framework's long-term design goals.

How are diagnostic IDs managed in ASP.NET Core?

Diagnostic IDs are cataloged in docs/list-of-diagnostics.md. When creating new analyzers or warnings, contributors must consult this file to assign the next sequential identifier (e.g., ASP0005). This centralized tracking prevents collisions between different diagnostic sources and maintains a searchable index of all compiler warnings and code analysis rules implemented in the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}