From 19a1338c469a9ed1c1fa27f64ba1a6591016f9fb Mon Sep 17 00:00:00 2001 From: Chidozie Ononiwu Date: Fri, 6 Nov 2020 15:58:16 -0800 Subject: [PATCH 1/2] Refactor eng/common/README.md --- README.md | 34 ++++++++++++++++++++++++++++++++++ eng/common/README.md | 28 ++-------------------------- 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1a900146de6..2504f422d4e 100644 --- a/README.md +++ b/README.md @@ -28,4 +28,38 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio [![Azure DevOps builds](https://img.shields.io/azure-devops/build/azure-sdk/internal/1372?label=eng%2Fcommon%20sync)](https://dev.azure.com/azure-sdk/internal/_build/latest?definitionId=1372&branchName=master) +## Common Engineering System + +The `eng/common` directory contains engineering files that are common across the various azure-sdk language repos. +It should remain relatively small and only contain textual based files like scripts, configs, or templates. It +should not contain binary files as they don't play well with git. + +### Code Structure + +To help keep the content of the `eng/common` directory as small as possible we should split the language specific parts of a common script out if possible. +- Keep the language specific logic as a function in the `eng/scripts/Language-Settings.ps1` files found in each language repo. +- Assign the function name to a variable in the `eng/common/scripts/common.ps1` file. +- Call the function using the variable name like so `&$VariableName`. + +### Updating + +Any updates to files in the `eng/common` directory should be made in the [azure-sdk-tools](https://github.com/azure/azure-sdk-tools) repo. +All changes made will cause a PR to created in all subscribed azure-sdk language repos which will blindly replace all contents of +the `eng/common` directory in that repo. For that reason do **NOT** make changes to files in this directory in the individual azure-sdk +languages repos as they will be overwritten the next time an update is taken from the common azure-sdk-tools repo. + +### Workflow + +The 'Sync eng/common directory' PRs will be created in the language repositories when a pull request that touches the eng/common directory is submitted against the master branch. This will make it easier for changes to be tested in each individual language repo before merging the changes in the azure-sdk-tools repo. The workflow is explained below: + +1. Create a PR (**Tools PR**) in the `azure-sdk-tools` repo with changes to eng/common directory. +2. `azure-sdk-tools - sync - eng-common` pipeline is triggered for the **Tools PR** +3. The `azure-sdk-tools - sync - eng-common` pipeline queues test runs for template pipelines in various languages. These help you test your changes in the **Tools PR**. +4. If there are changes in the **Tools PR** that will affect the release stage you should approve the release test pipelines by clicking the approval gate. The test (template) pipeline will automatically release the next eligible version without needing manual intervention for the versioning. Please approve your test releases as quickly as possible. A race condition may occur due to someone else queueing the pipeline and going all the way to release using your version while yours is still waiting. If this occurs manually rerun the pipeline that failed. +5. If you make additional changes to your **Tools PR** repeat steps 1 - 4 until you have completed the necessary testing of your changes. This includes full releases of the template package, if necessary. +6. Sign off on CreateSyncPRs stage of the sync pipeline using the approval gate. This stage will create the **Sync PRs** in the various language repos. A link to each of the **Sync PRs** will show up in the **Tools PR** for you to click and review. +7. Go review and approve each of your **Sync PRs**. +8. Sign Off on the VerifyAndMerge stage. This will merge any remaining open **Sync PR** and also append `auto-merge` to the **Tools PR**. + * If a **Sync PR** has any failing checks, it will need to be manually merged, even if `/check-enforcer override` has been run ([azure-sdk-tools#1147](https://github.com/Azure/azure-sdk-tools/issues/1147)). + C:/repo/sdk-tools/packages/java-packages/snippet-replacer-maven-plugin \ No newline at end of file diff --git a/eng/common/README.md b/eng/common/README.md index f85e3396ae4..6bb41f5904e 100644 --- a/eng/common/README.md +++ b/eng/common/README.md @@ -1,26 +1,2 @@ -# Common Engineering System - -The `eng/common` directory contains engineering files that are common across the various azure-sdk language repos. -It should remain relatively small and only contain textual based files like scripts, configs, or templates. It -should not contain binary files as they don't play well with git. - -## Updating - -Any updates to files in the `eng/common` directory should be made in the [azure-sdk-tools](https://github.com/azure/azure-sdk-tools) repo. -All changes made will cause a PR to created in all subscribed azure-sdk language repos which will blindly replace all contents of -the `eng/common` directory in that repo. For that reason do **NOT** make changes to files in this directory in the individual azure-sdk -languages repos as they will be overwritten the next time an update is taken from the common azure-sdk-tools repo. - -### Workflow - -The 'Sync eng/common directory' PRs will be created in the language repositories when a pull request that touches the eng/common directory is submitted against the master branch. This will make it easier for changes to be tested in each individual language repo before merging the changes in the azure-sdk-tools repo. The workflow is explained below: - -1. Create a PR (**Tools PR**) in the `azure-sdk-tools` repo with changes to eng/common directory. -2. `azure-sdk-tools - sync - eng-common` pipeline is triggered for the **Tools PR** -3. The `azure-sdk-tools - sync - eng-common` pipeline queues test runs for template pipelines in various languages. These help you test your changes in the **Tools PR**. -4. If there are changes in the **Tools PR** that will affect the release stage you should approve the release test pipelines by clicking the approval gate. The test (template) pipeline will automatically release the next eligible version without needing manual intervention for the versioning. Please approve your test releases as quickly as possible. A race condition may occur due to someone else queueing the pipeline and going all the way to release using your version while yours is still waiting. If this occurs manually rerun the pipeline that failed. -5. If you make additional changes to your **Tools PR** repeat steps 1 - 4 until you have completed the necessary testing of your changes. This includes full releases of the template package, if necessary. -6. Sign off on CreateSyncPRs stage of the sync pipeline using the approval gate. This stage will create the **Sync PRs** in the various language repos. A link to each of the **Sync PRs** will show up in the **Tools PR** for you to click and review. -7. Go review and approve each of your **Sync PRs**. -8. Sign Off on the VerifyAndMerge stage. This will merge any remaining open **Sync PR** and also append `auto-merge` to the **Tools PR**. - * If a **Sync PR** has any failing checks, it will need to be manually merged, even if `/check-enforcer override` has been run ([azure-sdk-tools#1147](https://github.com/Azure/azure-sdk-tools/issues/1147)). +## Common Engineering System +See [common engineering system docs](https://github.com/Azure/azure-sdk-tools/blob/master/README.md#common-engineering-system) From 7ac80280944c937338ac57fb0b29b711926ec06d Mon Sep 17 00:00:00 2001 From: Chidozie Ononiwu Date: Mon, 9 Nov 2020 13:56:30 -0800 Subject: [PATCH 2/2] Add doc directory --- README.md | 34 ---------------------------------- doc/README.md | 5 +++++ doc/common/common_engsys.md | 33 +++++++++++++++++++++++++++++++++ eng/common/README.md | 5 +++-- 4 files changed, 41 insertions(+), 36 deletions(-) create mode 100644 doc/README.md create mode 100644 doc/common/common_engsys.md diff --git a/README.md b/README.md index 2504f422d4e..1a900146de6 100644 --- a/README.md +++ b/README.md @@ -28,38 +28,4 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio [![Azure DevOps builds](https://img.shields.io/azure-devops/build/azure-sdk/internal/1372?label=eng%2Fcommon%20sync)](https://dev.azure.com/azure-sdk/internal/_build/latest?definitionId=1372&branchName=master) -## Common Engineering System - -The `eng/common` directory contains engineering files that are common across the various azure-sdk language repos. -It should remain relatively small and only contain textual based files like scripts, configs, or templates. It -should not contain binary files as they don't play well with git. - -### Code Structure - -To help keep the content of the `eng/common` directory as small as possible we should split the language specific parts of a common script out if possible. -- Keep the language specific logic as a function in the `eng/scripts/Language-Settings.ps1` files found in each language repo. -- Assign the function name to a variable in the `eng/common/scripts/common.ps1` file. -- Call the function using the variable name like so `&$VariableName`. - -### Updating - -Any updates to files in the `eng/common` directory should be made in the [azure-sdk-tools](https://github.com/azure/azure-sdk-tools) repo. -All changes made will cause a PR to created in all subscribed azure-sdk language repos which will blindly replace all contents of -the `eng/common` directory in that repo. For that reason do **NOT** make changes to files in this directory in the individual azure-sdk -languages repos as they will be overwritten the next time an update is taken from the common azure-sdk-tools repo. - -### Workflow - -The 'Sync eng/common directory' PRs will be created in the language repositories when a pull request that touches the eng/common directory is submitted against the master branch. This will make it easier for changes to be tested in each individual language repo before merging the changes in the azure-sdk-tools repo. The workflow is explained below: - -1. Create a PR (**Tools PR**) in the `azure-sdk-tools` repo with changes to eng/common directory. -2. `azure-sdk-tools - sync - eng-common` pipeline is triggered for the **Tools PR** -3. The `azure-sdk-tools - sync - eng-common` pipeline queues test runs for template pipelines in various languages. These help you test your changes in the **Tools PR**. -4. If there are changes in the **Tools PR** that will affect the release stage you should approve the release test pipelines by clicking the approval gate. The test (template) pipeline will automatically release the next eligible version without needing manual intervention for the versioning. Please approve your test releases as quickly as possible. A race condition may occur due to someone else queueing the pipeline and going all the way to release using your version while yours is still waiting. If this occurs manually rerun the pipeline that failed. -5. If you make additional changes to your **Tools PR** repeat steps 1 - 4 until you have completed the necessary testing of your changes. This includes full releases of the template package, if necessary. -6. Sign off on CreateSyncPRs stage of the sync pipeline using the approval gate. This stage will create the **Sync PRs** in the various language repos. A link to each of the **Sync PRs** will show up in the **Tools PR** for you to click and review. -7. Go review and approve each of your **Sync PRs**. -8. Sign Off on the VerifyAndMerge stage. This will merge any remaining open **Sync PR** and also append `auto-merge` to the **Tools PR**. - * If a **Sync PR** has any failing checks, it will need to be manually merged, even if `/check-enforcer override` has been run ([azure-sdk-tools#1147](https://github.com/Azure/azure-sdk-tools/issues/1147)). - C:/repo/sdk-tools/packages/java-packages/snippet-replacer-maven-plugin \ No newline at end of file diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000000..79754c91ce1 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,5 @@ +This folder contains some documentations for this repository. + +The folder structure is the following. + +- [common:](https://github.com/Azure/azure-sdk-tools/doc/common) contains documentation for engineering system common tools. \ No newline at end of file diff --git a/doc/common/common_engsys.md b/doc/common/common_engsys.md new file mode 100644 index 00000000000..71721e1058f --- /dev/null +++ b/doc/common/common_engsys.md @@ -0,0 +1,33 @@ +# Common Engineering System + +The `eng/common` directory contains engineering files that are common across the various azure-sdk language repos. +It should remain relatively small and only contain textual based files like scripts, configs, or templates. It +should not contain binary files as they don't play well with git. + +## Code Structure + +To help keep the content of the `eng/common` directory as small as possible we should split the language specific parts of a common script out if possible. +- Keep the language specific logic as a function in the `eng/scripts/Language-Settings.ps1` files found in each language repo. +- Assign the function name to a variable in the `eng/common/scripts/common.ps1` file. +- Call the function using the variable name like so `&$VariableName`. + +## Updating + +Any updates to files in the `eng/common` directory should be made in the [azure-sdk-tools](https://github.com/azure/azure-sdk-tools) repo. +All changes made will cause a PR to created in all subscribed azure-sdk language repos which will blindly replace all contents of +the `eng/common` directory in that repo. For that reason do **NOT** make changes to files in this directory in the individual azure-sdk +languages repos as they will be overwritten the next time an update is taken from the common azure-sdk-tools repo. + +## Workflow + +The 'Sync eng/common directory' PRs will be created in the language repositories when a pull request that touches the eng/common directory is submitted against the master branch. This will make it easier for changes to be tested in each individual language repo before merging the changes in the azure-sdk-tools repo. The workflow is explained below: + +1. Create a PR (**Tools PR**) in the `azure-sdk-tools` repo with changes to eng/common directory. +2. `azure-sdk-tools - sync - eng-common` pipeline is triggered for the **Tools PR** +3. The `azure-sdk-tools - sync - eng-common` pipeline queues test runs for template pipelines in various languages. These help you test your changes in the **Tools PR**. +4. If there are changes in the **Tools PR** that will affect the release stage you should approve the release test pipelines by clicking the approval gate. The test (template) pipeline will automatically release the next eligible version without needing manual intervention for the versioning. Please approve your test releases as quickly as possible. A race condition may occur due to someone else queueing the pipeline and going all the way to release using your version while yours is still waiting. If this occurs manually rerun the pipeline that failed. +5. If you make additional changes to your **Tools PR** repeat steps 1 - 4 until you have completed the necessary testing of your changes. This includes full releases of the template package, if necessary. +6. Sign off on CreateSyncPRs stage of the sync pipeline using the approval gate. This stage will create the **Sync PRs** in the various language repos. A link to each of the **Sync PRs** will show up in the **Tools PR** for you to click and review. +7. Go review and approve each of your **Sync PRs**. +8. Sign Off on the VerifyAndMerge stage. This will merge any remaining open **Sync PR** and also append `auto-merge` to the **Tools PR**. + * If a **Sync PR** has any failing checks, it will need to be manually merged, even if `/check-enforcer override` has been run ([azure-sdk-tools#1147](https://github.com/Azure/azure-sdk-tools/issues/1147)). \ No newline at end of file diff --git a/eng/common/README.md b/eng/common/README.md index 6bb41f5904e..91bd71ae8ae 100644 --- a/eng/common/README.md +++ b/eng/common/README.md @@ -1,2 +1,3 @@ -## Common Engineering System -See [common engineering system docs](https://github.com/Azure/azure-sdk-tools/blob/master/README.md#common-engineering-system) +# Common Engineering System + +Updates under this directory should only be made in the `azure-sdk-tools` repo as any changes under this directory outside of that repo will end up getting overwritten with future updates. For information about making updates see [common engineering system docs](https://github.com/Azure/azure-sdk-tools/doc/common/common_engsys.md#common-engineering-system)