Merge documentation changes from main to nightly (#6107)

Co-authored-by: Matt Thalman <mthalman@microsoft.com>

.github/ISSUE_TEMPLATE/releases/new-image-release.md

@@ -0,0 +1,50 @@
+---
+name: "Add new image"
+about: "Checklist for adding a new image to this repo"
+title: "Add image for ___"
+---
+
+## Nightly Branch Tasks
+
+1. - [ ] Update Dockerfiles and manifests
+    1. - [ ] Create Dockerfiles under
+        `/src/$product/$major-minor-version/$os/$arch/`. These Dockerfiles can contain placeholder
+        content, as they will be re-generated by templates later.
+    1. - [ ] If necessary, create new templates for [Dockerfiles](https://github.com/dotnet/dotnet-docker/tree/nightly/eng/dockerfile-templates)
+        and [Readmes](https://github.com/dotnet/dotnet-docker/tree/nightly/eng/readme-templates)
+            - See [CONTRIBUTING.md](https://github.com/dotnet/dotnet-docker/tree/nightly/CONTRIBUTING.md#editing-dockerfiles)
+        for instructions on editing templates.
+    1. - [ ] Update the [MAR tags metadata templates](https://github.com/dotnet/dotnet-docker/tree/nightly/eng/mcr-tags-metadata-templates)
+        to include the new images
+    1. - [ ] Update [manifest.json](https://github.com/dotnet/dotnet-docker/blob/nightly/manifest.json)
+        to reference the new set of Dockerfiles and templates with the appropriate tags.
+            - See the [supported tags policy](https://github.com/dotnet/dotnet-docker/blob/nightly/documentation/supported-tags.md)
+          to see which tagging patterns to follow.
+    1. - [ ] Run the commands to generate the Dockerfiles and READMEs based on templates:
+        1. - [ ] `pwsh .\eng\readme-templates\Get-GeneratedDockerfiles.ps1`
+        1. - [ ] `pwsh .\eng\readme-templates\Get-GeneratedReadmes.ps1`
+        1. - [ ] Inspect generated changes for correctness
+1. - [ ] Update tests
+    1. - [ ] Add new image to [`TestData.cs`](https://github.com/dotnet/dotnet-docker/blob/nightly/tests/Microsoft.DotNet.Docker.Tests/TestData.cs)
+    1. - [ ] Add unit tests and scenario tests. Follow existing patterns for other images.
+1. - [ ] Consider authoring sample Dockerfiles and adding them to [samples](https://github.com/dotnet/dotnet-docker/tree/main/samples)
+    1. - [ ] If not adding sample Dockerfiles, provide justification:
+1. - [ ] Run `build-and-test.ps1` to build and test your images
+        - See [CONTRIBUTING.md](https://github.com/dotnet/dotnet-docker/tree/nightly/CONTRIBUTING.md#editing-dockerfiles) for more detailed instructions
+1. - [ ] Commit changes
+1. - [ ] Create PR
+1. - [ ] Consider drafting an announcement to be posted on this repo's [discussions page](https://github.com/dotnet/dotnet-docker/discussions)
+    when images are published
+1. - [ ] Get PR signoff
+1. - [ ] Merge PR to nightly branch
+1. - [ ] Wait for automatically queued CI build to finish on [dotnet-docker-nightly pipeline](https://dev.azure.com/dnceng/internal/_build?definitionId=359) (internal MSFT link)
+1. - [ ] Confirm READMEs have been updated on [MAR](https://mcr.microsoft.com/en-us/catalog?search=dotnet) and [Docker Hub](https://hub.docker.com/r/microsoft/dotnet)
+
+## Main Branch Tasks
+
+1. - [ ] Merge the new distro changes to the main branch as part of the
+     [release process](https://github.com/dotnet/release/blob/main/.github/ISSUE_TEMPLATE/dotnet-docker-servicing-release.md)
+     for the next .NET release
+1. - [ ] Create announcement
+      - [ ] If the new distro is added for pre-release versions only, include the announcement in the new preview release announcement.
+      - [ ] If the new distro applies to in-support .NET versions, post a separate announcement. Example: [Alpine 3.20](https://github.com/dotnet/dotnet-docker/discussions/5556)

.github/ISSUE_TEMPLATE/releases/new-repo-onboarding.md

@@ -0,0 +1,95 @@
+# How to onboard a new repo
+
+> [!CAUTION] This guide is for .NET team members. If you are not a .NET team
+> member and you think we should add a new .NET image repo, please [file an
+> issue](https://github.com/dotnet/dotnet-docker/issues/new) detailing your
+> request and we will consider it!
+
+## Checklist
+
+1. - [ ] Read [CONTRIBUTING.md](https://github.com/dotnet/dotnet-docker/blob/main/CONTRIBUTING.md)
+1. - [ ] Decide on important characteristics of your container image offering proposal
+        - Support policy:
+            - Will you support only a single version or multiple versions at once?
+            - When a new version is released, how long are old releases supported for?
+            - Images must be published in the `nightly` branch before they can be added to the
+              `main` branch where they will be officially supported. Decide on what the bar is for
+              moving the new image repo from `nightly` to `main`.
+            - Decide how your team will handle the responsibility of responding to issues and
+              discussions about your images filed on this repo.
+        - Release process and cadence:
+            - Consider how your product's release cycle interacts with .NET's release cycle.
+            - How does you product handle security releases?
+        - Supported OSes:
+            - If your product is not intended to be extended or used as a base
+              image for users to build on, you may not need to publish
+              containers for more than one operating system.
+            - Azure Linux support is expected for Microsoft products.
+        - Distroless, non-distroless, or both:
+        - Repo name:
+        - Desired tags:
+            - See [supported tags policy](https://github.com/dotnet/dotnet-docker/blob/nightly/documentation/supported-tags.md) for existing images.
+1. - [ ] Document the above information in an [issue](https://github.com/dotnet/dotnet-docker/issues/new) proposing the new image repo.
+1. - [ ] [Create a prototype](#creating-a-prototype-image) and test out
+         your image. Gather feedback on the issue and make adjustments if necessary.
+1. - [ ] Once you have sign-off on proceeding with the implementation, then [create the new repo](#creating-a-new-repo).
+
+## Creating a prototype image
+
+This repo does not build any product source code. This is for a number of
+reasons:
+
+- Keeps container build times short
+- Keeps product build issues from blocking this repo's build and release
+  process
+
+With that in mind, you will need:
+
+- A binary archive of the product you want to ship in the container.
+  - On Linux, this should be a `.tar.gz` file.
+  - For Windows, it may be a `.zip` file.
+- The sha512 checksum of that binary.
+
+> [!TIP]
+> If you would like to gate the release of your product on container image
+> functionality, you should set up automation for pushing daily builds of your
+> product to this repo's `nightly` branch. That way, issues in the image build
+> can be surfaced every time there is a new build of the product.
+
+When creating the new Dockerfile, follow the [Dockerfile instructions best practices](https://docs.docker.com/build/building/best-practices/#dockerfile-instructions).
+Most images in this repo follow a simple pattern:
+
+1. Install dependencies
+1. Download an archive of the shipping product
+1. Validate its integrity with a checksum
+1. Install the product
+
+You can reference the various Dockerfiles in this repo for inspiration.
+
+## Creating a new repo
+
+For general instructions for adding new images to this repo, follow the
+[New Image Release](/.github/ISSUE_TEMPLATE/releases/new-image-release.md) checklist.
+
+1. - [ ] Create an issue for adding the new repo to the `nightly` branch.
+         It should contain the contents of this checklist as well as the contents of the
+         [New Image Release](/.github/ISSUE_TEMPLATE/releases/new-image-release.md) checklist.
+1. - [ ] Create a PR to add new repo and images to the `nightly` branch.
+         Follow the [New Image Release](/.github/ISSUE_TEMPLATE/releases/new-image-release.md)
+         checklist. The PR must include:
+    1. - [ ] Unit tests.
+    1. - [ ] Scenario tests.
+    1. - [ ] README content. This content will show up on
+        GitHub ([example](https://github.com/dotnet/dotnet-docker/blob/main/README.monitor.md)),
+        MAR, ([example](https://mcr.microsoft.com/artifact/mar/dotnet/monitor/about)), and
+        DockerHub ([example](https://hub.docker.com/r/microsoft/dotnet-monitor)).
+        It should contain:
+            - [ ] An "About" section explaining what the image is and why it's useful.
+            - [ ] A "Usage" section explaining the very basics for getting started with the image.
+            - [ ] Links to official documentation and examples.
+            - [ ] Links to official support policy.
+1. - [ ] Create a PR to add the new repo to the [MCR](https://github.com/microsoft/mcr) repo.
+    Example: [#3017](https://github.com/microsoft/mcr/pull/3017)
+1. - [ ] Merge the PR to the nightly branch
+1. - [ ] Create an issue for moving the new repo from the `nightly` to `main` branch according to
+         the guidelines that were decided on above.

.github/linters/.linkspector.yml

@@ -7,6 +7,6 @@ dirs:
 excludedDirs:
   - eng/readme-templates
 ignorePatterns:
-  - pattern: "^https://github.com/dotnet/release/blob/main/.github/ISSUE_TEMPLATE/dotnet-docker-servicing-release.md"
-  - pattern: "^l-is-the-package-in-the-linux-distro-base-image"
+  - pattern: "^https://github.com/microsoft/mcr.*$"
+  - pattern: "^https://github.com/dotnet/release.*$"
 useGitIgnore: true

.portal-docs/docker-hub/README.aspnet.md

@@ -42,7 +42,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ## Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/docker-hub/README.runtime-deps.md

@@ -28,7 +28,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ## Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/docker-hub/README.runtime.md

@@ -36,7 +36,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ## Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/docker-hub/README.samples.md

@@ -50,7 +50,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ## Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/mar/README.aspnet.portal.md

@@ -60,7 +60,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/mar/README.runtime-deps.portal.md

@@ -46,7 +46,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/mar/README.runtime.portal.md

@@ -54,7 +54,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

.portal-docs/mar/README.samples.portal.md

@@ -67,7 +67,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

CONTRIBUTING.md

@@ -49,22 +49,28 @@ The [`build-and-test.ps1`](https://github.com/dotnet/dotnet-docker/blob/main/bui
     > ./build-and-test.ps1 -Version 9.0
     ```
 
-- Build the 9.0 Nano Server 1809 images
+- Build the 9.0 Ubuntu Noble images using version and OS arguments. Note that this *will not* build `noble-chiseled` images as those are labeled by a different `OS` in [manifest.json](/manifest.json).
 
     ``` console
-    > ./build-and-test.ps1 -Version 9.0 -OS nanoserver-1809 -Mode Build
+    > ./build-and-test.ps1 -Version 9.0 -OS noble -Mode Build
+    ```
+
+- Build the 9.0 Ubuntu Noble images using Dockerfile paths. This *will* will build `noble-chiseled` images as those Dockerfiles will match the `noble` part of the `Paths` argument.
+
+    ``` console
+    > ./build-and-test.ps1 -Paths '*9.0*noble*' -Mode Build
     ```
 
 - Build and test the samples
 
     ``` console
-    > ./build-and-test.ps1 -Path *samples* -TestCategories sample
+    > ./build-and-test.ps1 -Paths '*samples*' -TestCategories sample
     ```
 
-- Test the 9.0 Ubuntu Noble images for the current architecture (e.g. x64, arm, arm64).
+- Test the 9.0 Nano Server 1809 images (remember to switch to Windows container mode in Docker Desktop)
 
     ``` console
-    > ./build-and-test.ps1 -Version 9.0 -OS noble -Mode Test
+    > ./build-and-test.ps1 -Version 9.0 -OS nanoserver-1809 -Mode Test
     ```
 
 ### Editing Dockerfiles
@@ -149,3 +155,14 @@ The following examples illustrate how to run `update-dependencies`:
     ``` console
     > dotnet run --project .\eng\update-dependencies\ -- 9.0 --product-version powershell=7.5.0 --compute-shas
     ```
+
+#### Checking Markdown links locally
+
+This repo uses [UmbrellaDocs/linkspector](https://github.com/UmbrellaDocs/linkspector)
+to automatically validate links in markdown files. You can run this tool
+locally using Docker.
+
+1. Build linkspector Docker image:
+   `docker build --no-cache --pull --build-arg LINKSPECTOR_PACKAGE= -t umbrelladocs/linkspector https://github.com/UmbrellaDocs/linkspector.git`
+2. Run linkspector:
+   `docker run --rm -it -v ${PWD}:/app umbrelladocs/linkspector bash -c 'linkspector check -c /app/.github/linters/.linkspector.yml'`

README.aspnet.md

@@ -44,7 +44,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

README.md

@@ -69,7 +69,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

README.runtime-deps.md

@@ -30,7 +30,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

README.runtime.md

@@ -38,7 +38,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features:
 

README.samples.md

@@ -52,7 +52,7 @@ The [Image Variants documentation](https://github.com/dotnet/dotnet-docker/blob/
 
 ### Distroless images
 
-.NET "distroless" container images contain only the minimal set of packages .NET needs, with everything else removed.
+.NET [distroless container images](https://github.com/dotnet/dotnet-docker/blob/main/documentation/distroless.md) contain only the minimal set of packages .NET needs, with everything else removed.
 Due to their limited set of packages, distroless containers have a minimized security attack surface, smaller deployment sizes, and faster start-up time compared to their non-distroless counterparts.
 They contain the following features: