# Understanding the Docs Directory in ASP.NET Core: A Complete Contributor Guide > Explore the aspnetcore docs directory. Discover its role as a contributor knowledge base for internal guides on building and testing the framework, not end-user API references. - Repository: [.NET Platform/aspnetcore](https://github.com/dotnet/aspnetcore) - Tags: how-to-guide - Published: 2026-08-01 --- **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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/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. ```bash # 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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/IssueManagementPolicies.md)** – Defines how issues are triaged and categorized. - **[`TriageProcess.md`](https://github.com/dotnet/aspnetcore/blob/main/TriageProcess.md)** – Details the weekly triage procedures used by the maintainers. ### Servicing and Patch Management **[`docs/Servicing.md`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/PreparingPatchUpdates.md)** to ensure proper targeting of servicing branches. **[`docs/SharedFramework.md`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/docs/Submodules.md)** provides critical guidance for working with the repository's Git submodules, while **[`Helix.md`](https://github.com/dotnet/aspnetcore/blob/main/Helix.md)** documents the Helix test infrastructure used for continuous integration across multiple platforms. ### Diagnostics and Tooling **[`docs/list-of-diagnostics.md`](https://github.com/dotnet/aspnetcore/blob/main/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. ```bash # Check for the next available diagnostic ID grep -n "ASP000" docs/list-of-diagnostics.md ``` **[`docs/tooling-consolidation.md`](https://github.com/dotnet/aspnetcore/blob/main/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: ```bash 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`](https://github.com/dotnet/aspnetcore/blob/main/APIReviewProcess.md): ```bash # 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: ```bash # 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`](https://github.com/dotnet/aspnetcore/blob/main/docs/README.md)** serves as the central index for all contributor documentation. - **[`BuildFromSource.md`](https://github.com/dotnet/aspnetcore/blob/main/BuildFromSource.md)** enables reliable cross-platform development environment setup. - **Process documents** like [`APIReviewProcess.md`](https://github.com/dotnet/aspnetcore/blob/main/APIReviewProcess.md) and [`Servicing.md`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/docs/BuildFromSource.md) and running the appropriate restore script for your platform ([`./restore.sh`](https://github.com/dotnet/aspnetcore/blob/main/./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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/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`](https://github.com/dotnet/aspnetcore/blob/main/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.