From 86257b38630cecbaf3dd230f6602ca6a7499916c Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 14 Dec 2017 06:11:10 -0500 Subject: [PATCH] Docs: Correct numbering and add integration test advice. --- docs/adding-new-rtypes.md | 20 +++++++++++++++----- docs/writing-providers.md | 6 +++--- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/adding-new-rtypes.md b/docs/adding-new-rtypes.md index 943aee04d..c07961dc9 100644 --- a/docs/adding-new-rtypes.md +++ b/docs/adding-new-rtypes.md @@ -54,7 +54,7 @@ a minimum. it to the end of the list.) * Mark the `bind` provider as supporting this record type by updating `dnscontrol/providers/bind/bindProvider.go` (look for `providers.CanUs` and you'll see what to do). -## Step 2: Add a helper function +## Step 3: Add a helper function Add a function to `pkg/js/helpers.js` for the new record type. This is the Javascript file that defines `dnsconfig.js`'s functions like @@ -68,13 +68,13 @@ your code conforms to our coding standard: npm install prettier node_modules/.bin/prettier --write pkg/js/helpers.js -## Step 3: Search for `#rtype_variations` +## Step 4: Search for `#rtype_variations` Anywhere a rtype requires special handling has been marked with a comment that includes the string `#rtype_variations`. Search for this string and add your new type to this code. -## Step 4: Add a `parse_tests` test case. +## Step 5: Add a `parse_tests` test case. Add at least one test case to the `pkg/js/parse_tests` directory. Test `013-mx.js` is a very simple one and is good for cloning. @@ -91,7 +91,7 @@ As you debug, if there are places that haven't been marked `#rtype_variations` that should be, add such a comment. Every time you do this, an angel gets its wings. -## Step 5: Add an `integrationTest` test case. +## Step 6: Add an `integrationTest` test case. Add at least one test case to the `integrationTest/integration_test.go` file. Look for `var tests =` and add the test to the end of this @@ -143,7 +143,7 @@ As you debug, if there are places that haven't been marked `#rtype_variations` that should be, add such a comment. If you fail to do this, God kills a cute little kitten. -## Step 6: Support more providers +## Step 7: Support more providers Now add support other providers. Add the `providers.CanUse...` flag to the provider and re-run the integration tests: @@ -154,3 +154,13 @@ For example, this will run the tests on Amazon AWS Route53: export R53_KEY_ID=CHANGE_TO_THE_ID export R53_KEY='CHANGE_TO_THE_KEY' go test -v -verbose -provider ROUTE53 + +The test should reveal any bugs. Keep iterating between fixing the +code and running the tests. When the tests all work, you are done. +(Well, you might want to clean up some code a bit, but at least you +know that everything is working.) + +If you find bugs that aren't covered by the tests, please please +please add a test that demonstrates the bug THEN fix the bug. This +will help all future contributors. If you need help with adding +tests, please ask! diff --git a/docs/writing-providers.md b/docs/writing-providers.md index 7b2b76c05..1ff8b848f 100644 --- a/docs/writing-providers.md +++ b/docs/writing-providers.md @@ -167,14 +167,14 @@ export R53_KEY='CHANGE_TO_THE_KEY' go test -v -verbose -provider ROUTE53 ``` -## Step 5: Update docs +## Step 8: Update docs * Edit [README.md](https://github.com/StackExchange/dnscontrol): Add the provider to the bullet list. * Edit [docs/provider-list.md](https://github.com/StackExchange/dnscontrol/blob/master/docs/provider-list.md): Add the provider to the provider list. * Create `docs/_providers/PROVIDERNAME.md`: Use one of the other files in that directory as a base. * Edit [OWNERS](https://github.com/StackExchange/dnscontrol/blob/master/OWNERS): Add the directory name and your github id. -## Step 6: Submit a PR +## Step 9: Submit a PR At this point you can submit a PR. @@ -183,7 +183,7 @@ input, or have questions. This is just a good stopping place to submit a PR if you haven't already. -## Step 7: Capabilities +## Step 10: Capabilities Some DNS providers have features that others do not. For example some support the SRV record. A provider announces what it can do using