diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cce174ef1..56e49a81d 100644
--- a/CONTRIBUTING.md
+++ b/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:
diff --git a/README.md b/README.md
index 2bd7e0249..b349f8930 100644
--- a/README.md
+++ b/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).
\ No newline at end of file
diff --git a/help/CreateImageAndAzureResources.md b/docs/create-image-and-azure-resources.md
similarity index 100%
rename from help/CreateImageAndAzureResources.md
rename to docs/create-image-and-azure-resources.md
diff --git a/help/debuggingFailedBuilds.md b/docs/debugging-failed-builds.md
similarity index 78%
rename from help/debuggingFailedBuilds.md
rename to docs/debugging-failed-builds.md
index 756531d25..d8a4c2ed8 100644
--- a/help/debuggingFailedBuilds.md
+++ b/docs/debugging-failed-builds.md
@@ -1,27 +1,27 @@
-# Debugging Failed Packer Builds
-
-## Step 1: Run packer build `-on-error=ask`
-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.
-`-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:
-
-
-
-## 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:
-
-
-
-Log into the Azure Portal. Find that resource group under `Resource groups`. You should see the resources for the Packer build:
-
-
-
-## Step 3: Connect to the VM
-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`:
-
-
-
+# Debugging Failed Packer Builds
+
+## Step 1: Run packer build `-on-error=ask`
+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.
+`-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:
+
+
+
+## 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:
+
+
+
+Log into the Azure Portal. Find that resource group under `Resource groups`. You should see the resources for the Packer build:
+
+
+
+## Step 3: Connect to the VM
+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`:
+
+
+
diff --git a/help/resources/askOnError.png b/docs/resources/askOnError.png
similarity index 100%
rename from help/resources/askOnError.png
rename to docs/resources/askOnError.png
diff --git a/help/resources/packerResourceGroup.png b/docs/resources/packerResourceGroup.png
similarity index 100%
rename from help/resources/packerResourceGroup.png
rename to docs/resources/packerResourceGroup.png
diff --git a/help/resources/resourceGroupName.png b/docs/resources/resourceGroupName.png
similarity index 100%
rename from help/resources/resourceGroupName.png
rename to docs/resources/resourceGroupName.png
diff --git a/help/resources/vmCredentials.png b/docs/resources/vmCredentials.png
similarity index 100%
rename from help/resources/vmCredentials.png
rename to docs/resources/vmCredentials.png
diff --git a/docs/software-and-images-guidelines.md b/docs/software-and-images-guidelines.md
new file mode 100644
index 000000000..27217d7ed
--- /dev/null
+++ b/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
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
GNU Fortran
Clang
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.
\ No newline at end of file