From 9a3a38f12532bb6f9cc1444635f1868c480da8f3 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Fri, 31 Jul 2020 12:42:57 -0700 Subject: [PATCH 1/3] Update documentation on darc --- docs/ReferenceResolution.md | 75 ++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 13 deletions(-) diff --git a/docs/ReferenceResolution.md b/docs/ReferenceResolution.md index c80d1a0acc03..4dc55e2d051f 100644 --- a/docs/ReferenceResolution.md +++ b/docs/ReferenceResolution.md @@ -100,16 +100,65 @@ is changing to `Microsoft.AspNetCore.BetterThanOrange`, you would need to make t ``` -## Updating dependencies manually - -If the `dotnet-maestro` bot has not correctly updated the dependencies, it may be worthwhile running `darc` manually: - -1. Install `darc` as described in -2. Run `darc update-dependencies --channel '.NET Core 3.1 Release'` - * Use `'trigger-subscriptions'` to prod the bot to create a PR if you do not want to make local changes - * Use `'.NET 3 Eng''` to update dependencies from dotnet/arcade - * Use `'.NET Eng - Latest'` to update dependencies from dotnet/arcade in the `master` branch - * Use `'VS Master'` to update dependencies from dotnet/roslyn in the `master` branch - * Use `'.NET 5 Dev'` to update dependencies from dotnet/efcore or dotnet/runtime in the `master` branch -3. `git diff` to confirm the tool's changes -4. Proceed with usual commit and PR +## A darc cheatsheet + +`darc` is a command-line tool that is used for dependency management in the dotnet ecosystem of repos. `darc` can be installed using the `darc-init` scripts located inside the `eng/common` directory. Once `darc` is installed, you'll need to set up the appropriate access tokens as outlined [in the official Darc docs](https://github.com/dotnet/arcade/blob/master/Documentation/Darc.md#setting-up-your-darc-client). + +Once `darc` is installed and set-up, it can be used to modify the subscriptions and dependencies in a project. + +**Getting the list of subscriptions in a repo** + +Subscriptions are objects that define the ecosystem repos we are listening for updates to, the frequency we are looking for updates, and more. + +``` +$ darc get-subscriptions --target-branch master --target-repo aspnetcore$ --regex +``` + +**Disable/enable a subscription** + +``` +$ darc subscription-status --id {subscriptionIdHere} --enable +$ darc subscription-status --id {subscriptionIdHere} --disable +``` + +**Trigger a subscription** + +Triggering a subscription will search for updates in its dependencies and open a PR in the target repo via the dotnet-maestro bot with these changes. + +``` +$ darc trigger-subscriptions --id {subscriptionIdHere} +``` + +**Manually update dependencies** + +If the `dotnet-maestro` bot has not correctly updated the dependencies, `darc update-dependencies` may be used to update the dependencies manually. Note, you'll need to run the commands below in a separate branch and submit a PR with the changes. These are the things that the bot would typically do for you if you use `trigger-subscriptions`. + +``` +$ darc update-dependencies --channel '.NET Core 3.1 Release' +$ darc update-depdendencies --channel '.NET 5 Dev' --source-repo efcore +``` + +Generally, using `trigger-subscriptions` is preferred for creating dependency updates instead of manually updating dependencies in your own PR. + +**Toggling batchability of subscription** + +Subscriptions can be batched. When a dependency update is detected, darc will bundle the commits for that update with existing dependency PRs. To toggle whether a subscription is batched or not, you will need to use the `update-subscription` command. + +``` +$ darc update-subscription --id {subscriptionIdHere} +``` + +Your shell's default editor will open and allow you to edit the metadata of the subscription. + +To disable batching, set `Batchable` to `False` and update the `Merge Policies` section with the following YAML. + +``` + - Name: Standard + Properties: {} +``` + +To enable batching, set `Batchable` to `True` and remove any `Merge Policies` set on the subscription. + +Note: Merge policies can only be set on unbatched subscriptions. Be sure to set/unset the `Merge Policies` field properly as you toggle batchability. + + From b796e7a5811a6e634ada7e010ec830e7474b2475 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Fri, 31 Jul 2020 13:34:26 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Doug Bunting <6431421+dougbu@users.noreply.github.com> --- docs/ReferenceResolution.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/ReferenceResolution.md b/docs/ReferenceResolution.md index 4dc55e2d051f..adc98db2b0d3 100644 --- a/docs/ReferenceResolution.md +++ b/docs/ReferenceResolution.md @@ -131,18 +131,18 @@ $ darc trigger-subscriptions --id {subscriptionIdHere} **Manually update dependencies** -If the `dotnet-maestro` bot has not correctly updated the dependencies, `darc update-dependencies` may be used to update the dependencies manually. Note, you'll need to run the commands below in a separate branch and submit a PR with the changes. These are the things that the bot would typically do for you if you use `trigger-subscriptions`. +If the `dotnet-maestro` bot has not correctly updated the dependencies, `darc update-dependencies` may be used to update the dependencies manually. Note, you'll need to run the commands below in a separate branch and submit a PR with the changes. These are the things that the bot should do for you if you use `trigger-subscriptions` or automatically (when the subscription fires e.g. about 15 minutes after a dependency's build completes if `Update Frequency: EveryBuild`). ``` $ darc update-dependencies --channel '.NET Core 3.1 Release' -$ darc update-depdendencies --channel '.NET 5 Dev' --source-repo efcore +$ darc update-dependencies --channel '.NET 5 Dev' --source-repo efcore ``` Generally, using `trigger-subscriptions` is preferred for creating dependency updates instead of manually updating dependencies in your own PR. **Toggling batchability of subscription** -Subscriptions can be batched. When a dependency update is detected, darc will bundle the commits for that update with existing dependency PRs. To toggle whether a subscription is batched or not, you will need to use the `update-subscription` command. +Subscriptions can be batched. When a dependency update is detected, `darc` will bundle the commits for that update with existing dependency PRs. To toggle whether a subscription is batched or not, you will need to use the `update-subscription` command. ``` $ darc update-subscription --id {subscriptionIdHere} @@ -161,4 +161,3 @@ To enable batching, set `Batchable` to `True` and remove any `Merge Policies` se Note: Merge policies can only be set on unbatched subscriptions. Be sure to set/unset the `Merge Policies` field properly as you toggle batchability. - From 4be24b0328fad3f93c286995d2bb19e05cf4e008 Mon Sep 17 00:00:00 2001 From: Safia Abdalla Date: Fri, 31 Jul 2020 13:35:41 -0700 Subject: [PATCH 3/3] Update code blocks in referenced assemblies --- docs/ReferenceResolution.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/ReferenceResolution.md b/docs/ReferenceResolution.md index adc98db2b0d3..8e94b2a86589 100644 --- a/docs/ReferenceResolution.md +++ b/docs/ReferenceResolution.md @@ -110,32 +110,32 @@ Once `darc` is installed and set-up, it can be used to modify the subscriptions Subscriptions are objects that define the ecosystem repos we are listening for updates to, the frequency we are looking for updates, and more. -``` -$ darc get-subscriptions --target-branch master --target-repo aspnetcore$ --regex +```bash +darc get-subscriptions --target-branch master --target-repo aspnetcore$ --regex ``` **Disable/enable a subscription** -``` -$ darc subscription-status --id {subscriptionIdHere} --enable -$ darc subscription-status --id {subscriptionIdHere} --disable +```bash +darc subscription-status --id {subscriptionIdHere} --enable +darc subscription-status --id {subscriptionIdHere} --disable ``` **Trigger a subscription** Triggering a subscription will search for updates in its dependencies and open a PR in the target repo via the dotnet-maestro bot with these changes. -``` -$ darc trigger-subscriptions --id {subscriptionIdHere} +```bash +darc trigger-subscriptions --id {subscriptionIdHere} ``` **Manually update dependencies** If the `dotnet-maestro` bot has not correctly updated the dependencies, `darc update-dependencies` may be used to update the dependencies manually. Note, you'll need to run the commands below in a separate branch and submit a PR with the changes. These are the things that the bot should do for you if you use `trigger-subscriptions` or automatically (when the subscription fires e.g. about 15 minutes after a dependency's build completes if `Update Frequency: EveryBuild`). -``` -$ darc update-dependencies --channel '.NET Core 3.1 Release' -$ darc update-dependencies --channel '.NET 5 Dev' --source-repo efcore +```bash +darc update-dependencies --channel '.NET Core 3.1 Release' +darc update-dependencies --channel '.NET 5 Dev' --source-repo efcore ``` Generally, using `trigger-subscriptions` is preferred for creating dependency updates instead of manually updating dependencies in your own PR. @@ -144,8 +144,8 @@ Generally, using `trigger-subscriptions` is preferred for creating dependency up Subscriptions can be batched. When a dependency update is detected, `darc` will bundle the commits for that update with existing dependency PRs. To toggle whether a subscription is batched or not, you will need to use the `update-subscription` command. -``` -$ darc update-subscription --id {subscriptionIdHere} +```bash +darc update-subscription --id {subscriptionIdHere} ``` Your shell's default editor will open and allow you to edit the metadata of the subscription.