DOCS: Improve docs/writing-providers.md wrt registrars and testing (#1366)

* DOCS: Improve docs/writing-providers.md wrt registars and testing
This commit is contained in:
Tom Limoncelli 2022-01-05 10:27:07 -05:00 committed by GitHub
parent 2f65533e1b
commit 368be4e57a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -98,8 +98,9 @@ into three general categories:
has A and MX records), you have to replace all the records at that
label. (GANDI_V5)
* **incremental-label-type:** Like incremental-record, but updates to any records at a label have to be done by type. For example, if a label (www.example.com) has many A and MX records, even the smallest change to one of the A records requires replacing all the A records. Any changes to the MX records requires replacing all the MX records. If an A record is converted to a CNAME, one must remove all the A records in one call, and add the CNAME record with another call. This is deceptively difficult to get right; if you have the choice between incremental-label-type and incremental-label, pick incremental-label. (DESEC, ROUTE53)
* **registrar only:** These providers are registrars but do not provide DNS service. (CSCGLOBAL, EASYNAME, INTERNETBS, OPENSRS)
All providers use the "diff" module to detect differences. It takes
All DNS providers use the "diff" module to detect differences. It takes
two zones and returns records that are unchanged, created, deleted,
and modified.
The zone providers use the
@ -128,10 +129,21 @@ Add the provider list so DNSControl knows it exists.
## Step 5: Implement
Implement all the calls in
[providers.DNSServiceProvider interface.](https://godoc.org/github.com/StackExchange/dnscontrol/providers#DNSServiceProvider).
**If you are implementing a DNS Service Provider:**
The function `GetDomainCorrections` is a bit interesting. It returns
Implement all the calls in the
[providers.DNSServiceProvider interface.](https://pkg.go.dev/github.com/StackExchange/dnscontrol/providers#DNSServiceProvider).
The function `GetDomainCorrections()` is a bit interesting. It returns
a list of corrections to be made. These are in the form of functions
that DNSControl can call to actually make the corrections.
**If you are implementing a DNS Registrar:**
Implement all the calls in the
[providers.Registrar interface.](https://pkg.go.dev/github.com/StackExchange/dnscontrol/providers#Registrar).
The function `GetRegistrarCorrections()` returns
a list of corrections to be made. These are in the form of functions
that DNSControl can call to actually make the corrections.
@ -171,6 +183,22 @@ export R53_KEY='CHANGE_TO_THE_KEY'
go test -v -verbose -provider ROUTE53
```
Some useful `go test` flags:
* Slow tests? Add `-timeout n` to increase the timeout for tests
* `go test` kills the tests after 10 minutes by default. Some providers need more time.
* This flag must be *before* the `-verbose` flag. Usually it is the first flag after `go test`.
* Example: `go test -timeout 20m -v -verbose -provider CLOUDFLAREAPI`
* Run only certain tests using the `-start` and `-end` flags.
* Rather than running all the tests, run just the tests you want.
* These flags must be *after* the `-provider FOO` flag.
* Example: `go test -v -verbose -provider ROUTE53 -start 10 -end 20` run tests 10-20 inclusive.
* Example: `go test -v -verbose -provider ROUTE53 -start 5 -end 5` runs only test 5.
* Example: `go test -v -verbose -provider ROUTE53 -start 20` skip the first 19 tests.
* Example: `go test -v -verbose -provider ROUTE53 -end 20` only run the first 20 tests.
* If a test will always fail because the provider doesn't support the feature, you can opt out of the test. Look at `func makeTests()` in [integrationTest/integration_test.go](https://github.com/StackExchange/dnscontrol/blob/2f65533e1b92c2967229a92a304fff7c14f7f4b6/integrationTest/integration_test.go#L675) for more details.
## Step 8: Update docs
* Edit [README.md](https://github.com/StackExchange/dnscontrol): Add the provider to the bullet list.