DOCS: Update docs related to diff2 and clean up useless mentions of diff2 (#2683)

Co-authored-by: Costas Drogos <costas.drogos@gmail.com>
Co-authored-by: imlonghao <git@imlonghao.com>
Co-authored-by: Jeffrey Cafferata <jeffrey@jcid.nl>
Co-authored-by: Vincent Hagen <blackshadev@users.noreply.github.com>

.github/workflows/pr_test.yml

@@ -91,7 +91,7 @@ jobs:
         ENV_CONTEXT: ${{ toJson(env) }}
         VARS_CONTEXT: ${{ toJson(vars) }}
         SECRETS_CONTEXT: ${{ toJson(secrets) }}
-  integrtests-diff2:
+  integration-tests:
     if: github.ref != 'refs/heads/master' && github.ref != 'refs/heads/main'
     runs-on: ubuntu-latest
     container:

documentation/byo-secrets.md

@@ -79,7 +79,7 @@ The line looks something like:
 
 2. Add your providers `_DOMAIN` env variable:
 
-Add it to the `env` section of `integrtests-diff2`.
+Add it to the `env` section of `integration-tests`.
 
 For example, the entry for BIND looks like:
 

documentation/release-engineering.md

@@ -143,7 +143,7 @@ GHA is configured to run an integration test for any provider listed in the "pro
 1. Edit `.github/workflows/pr_test.yml`
 2. Add the `FOO_DOMAIN` variable name of the provider to the "PROVIDERS" list.
 3. Set the `FOO_DOMAIN` variables in GHA via https://github.com/StackExchange/dnscontrol/settings/variables/actions
-4. All other variables should be stored as secrets (for consistency).  Add them to the `integrtests-diff2` section.
+4. All other variables should be stored as secrets (for consistency).  Add them to the `integration-tests` section.
 Set them in GHA via https://github.com/StackExchange/dnscontrol/settings/secrets/actions
 
 ### How do I add a "bring your own keys" integration test?

documentation/writing-providers.md

@@ -67,62 +67,42 @@ was confusing so we can update this document with advice for future
 authors (or even better, update [this document](https://github.com/StackExchange/dnscontrol/blob/master/documentation/writing-providers.md)
 yourself.)
 
-## NOTE: diff2
-
-We are in the process of changing how providers work. Sadly this document
-hasn't been fully updated yet.
-
-We are in the process of changing all providers from using `pkg/diff` to
-`pkg/diff2`.  diff2 is much easier to use as it does all the hard work for you.
-Providers are easier to write, there's less code for you to write, and fewer
-chances to make mistakes.
-
-New providers only need to implement diff2.  Older providers are implemented
-both ways, with a flag (`--diff2`) enabling the newer code.  Soon the new code
-will become the default, then the old code will be removed.
-
-The file `pkg/diff2/diff2.go` has instructions about how to use the new diff2 system.
-You can also do `grep diff2.By providers/*/*.go` to find providers that use
-the new system.
-
-Each DNS provider's API is different.  Some update one DNS record at a time.
-Others, the only change they permit is to upload the entire zone even if only one record changed!
-Others are somewhere in between: all records at a label must be updated at once, or all records
-in a RecordSet (the label + rType).  diff2 provides functions for all of these situations:
-
-diff2.ByRecord() -- Updates are done one DNS record at a time. New records are added. Changes and deletes refer to an ID assigned to the record by the provider.
-diff2.ByLabel() -- Updates are done for an entire label. Adds and changes are done by sending one or more records that will appear at that label (i.e. www.example.com). Deletes delete all records at that label.
-diff2.ByRecordSet() -- Similar to ByLabel() but updates are done on the label+type level. If www.example.com has 2 A records and 2 MX records, 
-
-
-
-
 ## Step 2: Pick a base provider
 
-Pick a similar provider as your base.  Providers basically fall
-into three general categories:
+It's a good idea to start by copying a similar provider.
 
-NOTE: diff2 changes this.  For now, you can simply run `grep diff2.By providers/*/*.go` to see which
-providers use ByZone, ByLabel, ByRecord, ByRecordSet and pick a similar provider to copy from.
+How can you tell a provider is similar?
 
-* **zone:** The API requires you to upload the entire zone every time. (BIND, NAMECHEAP).
-* **incremental-record:** The API lets you add/change/delete individual DNS records. (CLOUDFLARE, DNSIMPLE, NAMEDOTCOM, GCLOUD, HEXONET)
-* **incremental-label:** Like incremental-record, but if there are
-  multiple records on a label (for example, example www.example.com
-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. (EASYNAME, INTERNETBS, OPENSRS)
+Each DNS provider's API falls into one of 4 category. Some update one DNS record at a time.
+Others, the only change they permit is to upload the entire zone even if only one record changed!
+Others are somewhere in between: all records at a label must be updated at once, or all records
+in a RecordSet (the label + rType).
 
-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
-information to print a human-readable list of what is being changed,
-but upload the entire new zone.
-The incremental providers use the differences to
-update individual records or recordsets.
+In summary, provider APIs basically fall into four general categories:
 
+* Updates are done one record at a time (Record)
+* Updates are done one label at a time (Label)
+* Updates are done one label+type at a time (RecordSet)
+* Updates require the entire zone to be uploaded (Zone).
+
+To determine your provider's category, review your API documentation.
+
+To determine an existing provider's category, see which `diff2.By*()` function is used.
+
+DNSControl provides 4 helper functions that do all the hard work for
+you.  As input, they take the existing zone (what was downloaded via
+the API) and the desired zone (what is in `dnsconfig.js`).  They
+return a list of instructions. Implement handlers for the instructions
+and DNSControl is able to perform `dnscontrol push`.
+
+The functions are:
+
+* diff2.ByRecord() -- Updates are done one DNS record at a time. New records are added. Changes and deletes refer to an ID assigned to the record by the provider.
+* diff2.ByLabel() -- Updates are done for an entire label. Adds and changes are done by sending one or more records that will appear at that label (i.e. www.example.com). Deletes delete all records at that label.
+* diff2.ByRecordSet() -- Similar to ByLabel() but updates are done on the label+type level. If www.example.com has 2 A records and 2 MX records, updates must replace all the A records, or all the MX records, or add records of a different type.
+* diff2.ByZone() -- Updates are done by uploading the entire zone every time.
+
+The file `pkg/diff2/diff2.go` has instructions about how to use the diff2 system.
 
 ## Step 3: Create the driver skeleton
 
@@ -134,6 +114,7 @@ The main driver should be called `providers/name/nameProvider.go`.
 The API abstraction is usually in a separate file (often called
 `api.go`).
 
+Directory names should be consitent.  It should be all lowercase and match the ALLCAPS provider name.
 
 ## Step 4: Activate the driver