Document OS and software support strategy for virtual-environments (#3127)

CONTRIBUTING.md

@@ -15,7 +15,7 @@ Please note that this project is released with a [Contributor Code of Conduct][c
 1. [Fork][fork] and clone the repository
 1. Create a new branch: `git checkout -b my-branch-name`
 1. Make your changes, ensure that they include steps to install, validate post-install and update software report (please see [How to add new tool](CONTRIBUTING.md#how-to-add-new-tool) for details).
-1. Test your changes by [creating VHD and deploying a VM](help/CreateImageAndAzureResources.md).
+1. Test your changes by [creating VHD and deploying a VM](docs/create-image-and-azure-resources.md).
 1. Push to your fork and [submit a pull request][pr]
 
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:

README.md

@@ -1,5 +1,5 @@
 # GitHub Actions Virtual Environments
-This repository contains the source used to create the [virtual environments](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners) for GitHub Actions hosted runners, as well as the VM images of [Microsoft-hosted agents](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops#use-a-microsoft-hosted-agent) used for Azure Pipelines. To build a VM machine from this repo's source, see the [instructions](./help/CreateImageAndAzureResources.md).
+This repository contains the source used to create the [virtual environments](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners) for GitHub Actions hosted runners, as well as the VM images of [Microsoft-hosted agents](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops#use-a-microsoft-hosted-agent) used for Azure Pipelines. To build a VM machine from this repo's source, see the [instructions](docs/create-image-and-azure-resources.md).
 
 How to get in touch with us:
 - To file a bug report, or request tools to be added/updated, please [open an issue using the appropriate template](https://github.com/actions/virtual-environments/issues/new/choose)
@@ -34,21 +34,6 @@ The availability of images for GitHub Actions and Azure DevOps is different. See
 ***How to contribute to macOS source?*** macOS source lives in this repository and available for everyone. However, MacOS image-generation CI doesn't support external contributions yet so we are not able to accept pull-requests for now.
 We are in the process of preparing MacOS CI to accept contributions. Until then, we appreciate your patience and ask you continue to make tool requests by filing issues.
 
-## Software Guidelines
-In general, these are the guidelines we consider when deciding what to pre-install:
-
-- Tools and ecosystems that are broadly popular and widely-used will be given priority.
-- Recent versions of tools will be given priority over older versions.
-- Tools and versions that are deprecated or have reached end-of-life will not be added.
-- Tools and versions will typically be removed 6 months after they are deprecated or have reached end-of-life.
-- If a tool can be installed during the build, we will evaluate how much time is saved
- and how much space is used by having the tool pre-installed.
-- MIT, Apache, and GNU licenses are ok, anything else we'll have to check with lawyers.
-- If a tool takes much space we will evaluate space usage and provide a decision if this tool can be pre-installed.
-- If a tool requires the support of more than one version, we will consider the cost of this maintenance, how often new versions bring dangerous updates.
-
-**Note:** For new tools, please, create an issue and get an approval from us to add this tool to the image before creating the pull request.
-
 ## Updates to virtual environments
 *Cadence*
 
@@ -68,6 +53,9 @@ You can also track upcoming changes using the [awaiting-deployment](https://gith
 [ubuntu-16.04]: https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu1604-README.md
 [Windows-2019]: https://github.com/actions/virtual-environments/blob/main/images/win/Windows2019-Readme.md
 [windows-2016]: https://github.com/actions/virtual-environments/blob/main/images/win/Windows2016-Readme.md
-[macOS-10.15]: https://github.com/actions/virtual-environments/blob/main/images/macos/macos-10.15-Readme.md
 [macOS-11.0]: https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11.0-Readme.md
+[macOS-10.15]: https://github.com/actions/virtual-environments/blob/main/images/macos/macos-10.15-Readme.md
 [self-hosted runners]: https://help.github.com/en/actions/hosting-your-own-runners
+
+## Software and image guidelines
+To learn more about tools and images support policy, see the [guidelines](./docs/software-and-images-guidelines.md).

docs/debugging-failed-builds.md

@@ -1,27 +1,27 @@
-# Debugging Failed Packer Builds
+# Debugging Failed Packer Builds
-
+
-## Step 1: Run packer build `-on-error=ask`
+## Step 1: Run packer build `-on-error=ask`
-When you run the `packer build` command, give it the `-on-error=ask` flag.
+When you run the `packer build` command, give it the `-on-error=ask` flag.
-By default, `packer build` will delete the resource group as soon as the build fails.
+By default, `packer build` will delete the resource group as soon as the build fails.
-`-on-error=ask` will pause it and wait for your input so you have time to remote in to the VM and diagnose the failure.
+`-on-error=ask` will pause it and wait for your input so you have time to remote in to the VM and diagnose the failure.
-
+
-When the build fails, you will see this:
+When the build fails, you will see this:
-
+
-![Ask on error screenshot](/help/resources/askOnError.png "Ask on error screenshot")
+![Ask on error screenshot](/docs/resources/askOnError.png "Ask on error screenshot")
-
+
-## Step 2: Find the resource group name in the build log
+## Step 2: Find the resource group name in the build log
-At the beginning of the build log (written to console), find the resource group name for the VM:
+At the beginning of the build log (written to console), find the resource group name for the VM:
-
+
-![Resource group from log screenshot](/help/resources/resourceGroupName.png "Resource group from log screenshot")
+![Resource group from log screenshot](/docs/resources/resourceGroupName.png "Resource group from log screenshot")
-
+
-Log into the Azure Portal.  Find that resource group under `Resource groups`.  You should see the resources for the Packer build:
+Log into the Azure Portal.  Find that resource group under `Resource groups`.  You should see the resources for the Packer build:
-
+
-![Packer resource group in Azure screenshot](/help/resources/packerResourceGroup.png "Packer resource group in Azure screenshot")
+![Packer resource group in Azure screenshot](/docs/resources/packerResourceGroup.png "Packer resource group in Azure screenshot")
-
+
-## Step 3: Connect to the VM
+## Step 3: Connect to the VM
-Select the VM in the resource group.  Click `Connect:`
+Select the VM in the resource group.  Click `Connect:`
-
+
-This will download an RDP file.  Open that and enter the credentials found in the JSON file you pass to `packer build`:
+This will download an RDP file.  Open that and enter the credentials found in the JSON file you pass to `packer build`:
-
+
-![VM credentials screenshot](/help/resources/vmCredentials.png "VM credentials screenshot")
+![VM credentials screenshot](/docs/resources/vmCredentials.png "VM credentials screenshot")
-
+

docs/software-and-images-guidelines.md

@@ -0,0 +1,37 @@
+# Software and image guidelines
+
+## Software preinstallation policy
+In general, these are the guidelines we consider when deciding what to pre-install:
+
+- Tools and ecosystems that are broadly popular and widely-used will be given priority.
+- Recent versions of tools will be given priority over older versions.
+- Tools and versions that are deprecated or have reached end-of-life will not be added.
+- If a tool can be installed during the build, we will evaluate how much time is saved
+ and how much space is used by having the tool pre-installed.
+- MIT, Apache, and GNU licenses are ok, anything else we'll have to check with lawyers.
+- If a tool takes much space we will evaluate space usage and provide a decision if this tool can be pre-installed.
+- If a tool requires the support of more than one version, we will consider the cost of this maintenance, how often new versions bring dangerous updates.
+
+**Note:** For new tools, please, create an issue and get an approval from us to add this tool to the image before creating the pull request.
+
+## Software and images support policy
+These are the guidelines we follow in software and images supporting routine:
+- Tools and versions will typically be removed 6 months after they are deprecated or have reached end-of-life.
+- We support at least 2 latest OS versions (LTS only for Ubuntu) and initiate deprecation process for the oldest one when image usage drops below 5%.
+- Most of the tools are preinstalled in the latest version only.
+- Popular tools can have several versions installed side-by-side with the following strategy:
+
+| Tool name | Installation strategy |
+|-----------|-----------------------|
+| Java      | all LTS versions |
+| Node.js   | 3 latest LTS versions |
+| Go        | 3 latest minor versions     |
+| Python <br/> Ruby | 5 most popular `major.minor` versions |
+| PyPy      | 3 most popular `major.minor` versions |
+| .NET Core | 2 latest LTS versions and 1 latest version. For each feature version only latest patch is installed |
+| GCC <br/> GNU Fortran <br/> Clang <br/> GNU C++ | 3 latest major versions |
+| Android NDK | 1 latest, 1 LTS version |
+| Xcode     | all OS compatible versions, latest beta for each new version |
+
+## Software default versions update policy for tools with multiple versions installed
+In general, once a new version is installed on the image, we announce the default version update 2 weeks prior to deploying it to give time to adapt to upcoming changes. For potentially dangerous updates, we can extend the timeline up to 1 month between the announcement and deployment.