diff --git a/docs/PackageArchives.md b/docs/PackageArchives.md deleted file mode 100644 index 420e0906dfba..000000000000 --- a/docs/PackageArchives.md +++ /dev/null @@ -1,62 +0,0 @@ -Package Archives -================ - -This repo builds multiple package archives which contain a NuGet fallback folder (also known as the fallback or offline package cache). The fallback folder is a set of NuGet packages that is bundled in the .NET Core SDK installers and available in Azure Web App service. - -Package archives are available in four varieties. - -* **LZMA** - `nuGetPackagesArchive-$(Version).lzma` - The LZMA is a compressed file format, similar to a .zip. On first use or on install, the .NET Core CLI will expand this LZMA file, extracting the packages inside to %DOTNET_INSTALL_DIR%/sdk/NuGetFallbackFolder. This contains all NuGet packages and their complete contents. -* **ci-server** - `nuGetPackagesArchive-ci-server-$(Version).zip` - this archive is optimized for CI server environments. It contains the same contents as the LZMA, but trimmed of xml docs (these are only required for IDEs) and .nupkg files (not required for NuGet as for the 2.0 SDK). -* **ci-server-patch** - `nuGetPackagesArchive-ci-server-$(Version).patch.zip` - this archive is the same as the ci-server archive, but each release is incremental - i.e. it does not bundle files that were present in a previous ci-server archive release. This can be used by first starting with a baseline `nuGetPackagesArchive-ci-server-$(Version).zip` and then applying the `.patch.zip` version for subsequent updates. -* **ci-server-compat-patch** - `nuGetPackagesArchive-ci-server-compat-$(Version).patch.zip` - similar to the ci-server-patch archive, but this includes .nupkg files to satisfy CI environments that may have older NuGet clients. - -These archives are built using the projects in [src/PackageArchive/Archive.\*/](/src/PackageArchive/). - -## Using a fallback folder - -NuGet restore takes a list of fallback folders in the MSBuild property `RestoreAdditionalProjectFallbackFolders`. Unlike a folder restore source, restore will not copy the packages from a fallback folder into the global NuGet cache. - -By default, the .NET Core SDK adds `$(DotNetInstallRoot)/sdk/NuGetFallbackFolder/` to this list. The .NET Core CLI expands its bundled `nuGetPackagesArchive.lzma` file into this location on first use or when the installers run. (See [Microsoft.NET.NuGetOfflineCache.targets](https://github.com/dotnet/sdk/blob/v2.1.300/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.NuGetOfflineCache.targets)). - -## Scenarios - -The following scenarios are used to determine which packages go into the fallback package cache. -These requirements are formalized as project files in [src/PackageArchive/Scenario.\*/](/src/PackageArchive/). - - - A user should be able to restore the following templates and only use packages from the offline cache: - - `dotnet new console` - - `dotnet new library` - - `dotnet new web` - - `dotnet new razor` - - `dotnet new mvc` - -The following packages are NOT included in the offline cache. - - Packages required for standalone publishing, aka projects that set a Runtime Identifier during restore - - Packages required for F# and VB templates - - Packages required for Visual Studio code generation in ASP.NET Core projects - - Packages required to restore .NET Framework projects - - Packages required to restore test projects, such as xunit, MSTest, NUnit - -The result of this typically means including the transitive graph of the following packages: - - - Packages that match bundled runtimes - - Microsoft.NETCore.App - - Microsoft.AspNetCore.App - - Packages that Microsoft.NET.Sdk adds implicitly - - Microsoft.NETCore.App - - NETStandard.Library - -### Example - -Given the following parameters: - - LatestNETCoreAppTFM = netcoreapp2.1 - - DefaultRuntimeVersion = 2.1 - - BundledRuntimeVersion = 2.1.8 - - BundledAspNetRuntimeVersion = 2.1.7 - - LatestNETStandardLibraryTFM = netstandard2.0 - - BundledNETStandardLibraryVersion = 2.0.1 - -The LZMA should contain - - Microsoft.NETCore.App/2.1.0 + netcoreapp2.1 dependencies (Microsoft.NET.Sdk will implicitly reference "2.1", which NuGet to 2.1.0) - - Microsoft.NETCore.App/2.1.8 + netcoreapp2.1 dependencies (Matches the runtime in shared/Microsoft.NETCore.App/2.1.8/) - - NETStandard.Library/2.0.1 + netstandard2.0 dependencies (Microsoft.NET.Sdk will implicitly reference "2.0.1") diff --git a/docs/README.md b/docs/README.md index 230b8d7f5173..67400982b4dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,8 +4,23 @@ Contributor documentation The primary audience for documentation in this folder is contributors to ASP.NET Core. If you are looking for documentation on how to *use* ASP.NET Core, go to . -# ASP.NET Core developer workflow +> :bulb: If you're a new contributor looking to set up the repo locally, the [build from source documentation](BuildFromSource.md) is the best place to start. -- [Building from source](BuildFromSource.md) -- [Troubleshooting build errors](BuildErrors.md) -- [Artifacts structure](Artifacts.md) +The table below outlines the different docs in this folder and what they are helpful for. + +| Documentation | What is it about? | Who is it for? | +|--------------------------------------------------------------------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| +| [API review process](APIReviewProcess.md) | Outlines the process for reviewing API changes in ASP.NET Core | Anyone looking to understand the process for making API changes to ASP.NET Core | +| [Artifacts structure](Artifacts.md) | Outlines the artifacts produced by the build | Anyone looking to understand artifiacts produced from an Azure DevOps build | +| [Troubleshooting build errors](BuildErrors.md) | Common errors that occur when building the repo and how to resolve them | Anyone running into an issue with the build | +| [Building from source](BuildFromSource.md) | Setup instructions for the ASP.NET Core repo | First-time contributors | +| [Working with EventSources and EventCounters](EventSourceAndCounters.md) | Guidance on adding event tracing to a library | Anyone needing to add event tracing for diagnostics purposes | +| [Tests on Helix](Helix.md) | An overview of the Helix test environment | Anyone debugging tests in Helix or looking to understand the output from Helix builds | +| [Issue management](IssueManagementPolicies.md) | Overview of policies in place to manage issues| Community members and collaborators looking to understand how we handle closed issue, issues that need author feedback, etc | | +| [Preparing a patch update](PreparingPatchUpdates.md) | Documentation on how to setup for a patch release of ASP.NET Core | Anyone looking to publish servicing updates | +| [Project properties](ProjectProperties.md) | Overview of configurable MSBuild properties on the repo | Anyone looking to modify how a project is packaged | +| [How references are resolved](ReferenceResolution.md) | Overview of dependency reference setup in the repo | Anyone looking to understand how package references are configured in the repo | +| [Servicing changes](Servicing.md) | Documentation on how to submit servicing PRs to previous releases | Anyone to submit patches or backports to prior releases, contains the "Shiproom Template" | +| [Shared framework](SharedFramework.md) | Overview of the ASP.NET Core Shared framework | Anyone looking to understand the policies in place for managing the code of the shared framework | +| Submodules | Documentation on working with submodules in Git | Anyone working with submodules in the repo | +| [Triage process](TriageProcess.md)| Overview of the issue triage process used in the repo | Anyone looking to understand the triage process on the repo |