From 2cbd819f4a3c61fd008f509cf263934e61d11c80 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Wed, 18 Dec 2024 15:58:39 -0500 Subject: [PATCH 1/6] DOC: NEW: How to test a branch --- documentation/SUMMARY.md | 1 + documentation/test-a-branch.md | 69 ++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 documentation/test-a-branch.md diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md index 55c8babf4f..a65e5b34eb 100644 --- a/documentation/SUMMARY.md +++ b/documentation/SUMMARY.md @@ -186,6 +186,7 @@ * [Writing new DNS providers](writing-providers.md) * [Creating new DNS Resource Types (rtypes)](adding-new-rtypes.md) * [Integration Tests](integration-tests.md) +* [Test a branch](test-a-branch.md) * [Unit Testing DNS Data](unittests.md) * [Bug Triage Process](bug-triage.md) * [Bring-Your-Own-Secrets for automated testing](byo-secrets.md) diff --git a/documentation/test-a-branch.md b/documentation/test-a-branch.md new file mode 100644 index 0000000000..774481cddd --- /dev/null +++ b/documentation/test-a-branch.md @@ -0,0 +1,69 @@ +### Test A Branch + +Instructions for testing DNSControl at a particular PR or branch. + +## Using Docker + +Using Docker assures you're using the latest version of Go and doesn't require you to install anything on your machine, other than Docker! + +Assumptions: +* `/THE/PATH` -- Change this to the full path to where your dnsconfig.js and other files are located. +* `INSERT_BRANCH_HERE` -- The branch you want to test. The branch associated with a PR is listed on [https://github.com/StackExchange/dnscontrol/branches](https://github.com/StackExchange/dnscontrol/branches). + +``` +docker run -it -v /THE/PATH:/dns golang +git clone https://github.com/StackExchange/dnscontrol.git +cd dnscontrol +git checkout INSERT_BRANCH_HERE +go install + +cd /dns +dnscontrol preview +``` + +If you want to run the integration tests, follow the +[Integration Tests](https://docs.dnscontrol.org/developer-info/integration-tests) document +as usual. The directory to be in is `/go/dnscontrol/integrationTest`. + +``` +cd /go/dnscontrol/integrationTest +go test -v -verbose -provider INSERT_PROVIDER_NAME -start 1 -end 3 +``` + +Change `INSERT_PROVIDER_NAME` to the name of your provider (BIND, ROUTE53, GCLOUD, etc.) + + +## Not using Docker + +Assumptions: +* `/THE/PATH` -- Change this to the full path to where your dnsconfig.js and other files are located. +* `INSERT_BRANCH_HERE` -- The branch you want to test. The branch associated with a PR is listed on [https://github.com/StackExchange/dnscontrol/branches](https://github.com/StackExchange/dnscontrol/branches). + +Step 1: Install Go + +[https://go.dev/dl/](https://go.dev/dl/) + +Step 2: Check out the software + +``` +git clone https://github.com/StackExchange/dnscontrol.git +cd dnscontrol +git checkout INSERT_BRANCH_HERE +go install + +cd /THE/PATH +dnscontrol preview +``` + +Step 3: Clean up + +`go install` put the `dnscontrol` program in your `$HOME/bin` directory. You probably want to remove it. + +``` +$ rm -i $HOME/bin/dnscontrol +``` + +## Other useful docs + +* How to run the integrations tests: + * [https://docs.dnscontrol.org/developer-info/integration-tests](https://docs.dnscontrol.org/developer-info/integration-tests) From 37cd87ff31b696fc598b95f90c9049de5e15250f Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Thu, 19 Dec 2024 16:25:59 +0100 Subject: [PATCH 2/6] DOCS: Code syntax highlighting. --- documentation/test-a-branch.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/documentation/test-a-branch.md b/documentation/test-a-branch.md index 774481cddd..8185e8ac18 100644 --- a/documentation/test-a-branch.md +++ b/documentation/test-a-branch.md @@ -10,13 +10,15 @@ Assumptions: * `/THE/PATH` -- Change this to the full path to where your dnsconfig.js and other files are located. * `INSERT_BRANCH_HERE` -- The branch you want to test. The branch associated with a PR is listed on [https://github.com/StackExchange/dnscontrol/branches](https://github.com/StackExchange/dnscontrol/branches). -``` +```shell docker run -it -v /THE/PATH:/dns golang git clone https://github.com/StackExchange/dnscontrol.git cd dnscontrol git checkout INSERT_BRANCH_HERE go install +``` +```shell cd /dns dnscontrol preview ``` @@ -25,12 +27,12 @@ If you want to run the integration tests, follow the [Integration Tests](https://docs.dnscontrol.org/developer-info/integration-tests) document as usual. The directory to be in is `/go/dnscontrol/integrationTest`. -``` +```shell cd /go/dnscontrol/integrationTest go test -v -verbose -provider INSERT_PROVIDER_NAME -start 1 -end 3 ``` -Change `INSERT_PROVIDER_NAME` to the name of your provider (BIND, ROUTE53, GCLOUD, etc.) +Change `INSERT_PROVIDER_NAME` to the name of your provider (`BIND`, `ROUTE53`, `GCLOUD`, etc.) ## Not using Docker @@ -45,12 +47,14 @@ Step 1: Install Go Step 2: Check out the software -``` +```shell git clone https://github.com/StackExchange/dnscontrol.git cd dnscontrol git checkout INSERT_BRANCH_HERE go install +``` +```shell cd /THE/PATH dnscontrol preview ``` @@ -59,8 +63,8 @@ Step 3: Clean up `go install` put the `dnscontrol` program in your `$HOME/bin` directory. You probably want to remove it. -``` -$ rm -i $HOME/bin/dnscontrol +```shell +rm -i $HOME/bin/dnscontrol ``` ## Other useful docs From da3c58b8468ab39d3aef2d1af186a084183b27ef Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Thu, 19 Dec 2024 16:26:59 +0100 Subject: [PATCH 3/6] DOCS: Deduplication of the assumptions. --- documentation/test-a-branch.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/documentation/test-a-branch.md b/documentation/test-a-branch.md index 8185e8ac18..3e56048e53 100644 --- a/documentation/test-a-branch.md +++ b/documentation/test-a-branch.md @@ -2,14 +2,14 @@ Instructions for testing DNSControl at a particular PR or branch. -## Using Docker - -Using Docker assures you're using the latest version of Go and doesn't require you to install anything on your machine, other than Docker! - Assumptions: * `/THE/PATH` -- Change this to the full path to where your dnsconfig.js and other files are located. * `INSERT_BRANCH_HERE` -- The branch you want to test. The branch associated with a PR is listed on [https://github.com/StackExchange/dnscontrol/branches](https://github.com/StackExchange/dnscontrol/branches). +## Using Docker + +Using Docker assures you're using the latest version of Go and doesn't require you to install anything on your machine, other than Docker! + ```shell docker run -it -v /THE/PATH:/dns golang git clone https://github.com/StackExchange/dnscontrol.git @@ -34,13 +34,8 @@ go test -v -verbose -provider INSERT_PROVIDER_NAME -start 1 -end 3 Change `INSERT_PROVIDER_NAME` to the name of your provider (`BIND`, `ROUTE53`, `GCLOUD`, etc.) - ## Not using Docker -Assumptions: -* `/THE/PATH` -- Change this to the full path to where your dnsconfig.js and other files are located. -* `INSERT_BRANCH_HERE` -- The branch you want to test. The branch associated with a PR is listed on [https://github.com/StackExchange/dnscontrol/branches](https://github.com/StackExchange/dnscontrol/branches). - Step 1: Install Go [https://go.dev/dl/](https://go.dev/dl/) From 555f77da285f0c96faa694aac8c4dc0b940adc5a Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Thu, 19 Dec 2024 16:28:45 +0100 Subject: [PATCH 4/6] DOCS: This link should be relative. --- documentation/test-a-branch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/test-a-branch.md b/documentation/test-a-branch.md index 3e56048e53..dff9023643 100644 --- a/documentation/test-a-branch.md +++ b/documentation/test-a-branch.md @@ -24,7 +24,7 @@ dnscontrol preview ``` If you want to run the integration tests, follow the -[Integration Tests](https://docs.dnscontrol.org/developer-info/integration-tests) document +[Integration Tests](integration-tests.md) document as usual. The directory to be in is `/go/dnscontrol/integrationTest`. ```shell From 57ad3cb308d8f3e2b689c1b8baad4f4a6ccde4d1 Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Thu, 19 Dec 2024 16:31:41 +0100 Subject: [PATCH 5/6] DOCS: The `git checkout` command can be combined with the `git clone` command. --- documentation/test-a-branch.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/documentation/test-a-branch.md b/documentation/test-a-branch.md index dff9023643..0850850844 100644 --- a/documentation/test-a-branch.md +++ b/documentation/test-a-branch.md @@ -12,9 +12,8 @@ Using Docker assures you're using the latest version of Go and doesn't require y ```shell docker run -it -v /THE/PATH:/dns golang -git clone https://github.com/StackExchange/dnscontrol.git +git clone -b INSERT_BRANCH_HERE https://github.com/StackExchange/dnscontrol.git cd dnscontrol -git checkout INSERT_BRANCH_HERE go install ``` @@ -43,9 +42,8 @@ Step 1: Install Go Step 2: Check out the software ```shell -git clone https://github.com/StackExchange/dnscontrol.git +git clone -b INSERT_BRANCH_HERE https://github.com/StackExchange/dnscontrol.git cd dnscontrol -git checkout INSERT_BRANCH_HERE go install ``` From 58423222dde59ce0d889a9ae7642b345a3df127a Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Thu, 19 Dec 2024 16:32:53 +0100 Subject: [PATCH 6/6] DOCS: Add `--single-branch` to prevent fetching of all branches. --- documentation/test-a-branch.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/test-a-branch.md b/documentation/test-a-branch.md index 0850850844..07f7e3dbcb 100644 --- a/documentation/test-a-branch.md +++ b/documentation/test-a-branch.md @@ -12,7 +12,7 @@ Using Docker assures you're using the latest version of Go and doesn't require y ```shell docker run -it -v /THE/PATH:/dns golang -git clone -b INSERT_BRANCH_HERE https://github.com/StackExchange/dnscontrol.git +git clone -b INSERT_BRANCH_HERE --single-branch https://github.com/StackExchange/dnscontrol.git cd dnscontrol go install ``` @@ -42,7 +42,7 @@ Step 1: Install Go Step 2: Check out the software ```shell -git clone -b INSERT_BRANCH_HERE https://github.com/StackExchange/dnscontrol.git +git clone -b INSERT_BRANCH_HERE --single-branch https://github.com/StackExchange/dnscontrol.git cd dnscontrol go install ```