A pass at documenting the provider details and best practices in the …

…README

CHANGELOG.md

@@ -1,3 +1,3 @@
-## TODO: v0.0.1 - 20??-??-?? - Moving
+## v0.0.1 - 2023-08-21 - Initial (Alpha) Release
 
-Initial release
+It exists

README.md

@@ -32,11 +32,90 @@ octodns-spf==0.0.1
 
 ### Configuration
 
+#### Options & Defaults
+
 ```yaml
 providers:
-  spf:
+  spf-google:
     class: octodns_spf.SpfSource
-    # TODO
+    # See https://datatracker.ietf.org/doc/html/rfc7208#section-5 for the
+    # details of the various mechinisms below. Each is an array of zero or more
+    # items to be added to the SPF record. Mechinisms are specified in the order
+    # the parameters are listed below and value order is preserved.
+    # (default: empty list)
+    a_records: []
+    mx_records: []
+    ip4_addresses: []
+    ip6_addresses: []
+    includes: []
+    exists: []
+    # The "all" value to be appended onto the SPF value, there's not a clear
+    # consensus on best practice here, but there does seem to be a slight leaning
+    # towards hard-failing, "-all". Soft-fail can be enabled by setting this
+    # value to `true`. If for some reason you donot want to specify a fail mode,
+    # this can be set to `null` and it will be ommited.
+    # See https://news.ycombinator.com/item?id=34344590 for some discussion
+    # (default: false, hard fail)
+    soft_fail: false
+    # Wether or not this provider will merge it's configuration with any
+    # prexisting SPF value in an APEX TXT record. If `false` an error will be
+    # thrown. If `true` the existing values, wether from a previous SpfSource or
+    # any other provider, will be preserved and this provider's config will be
+    # appended onto each mechinism.
+    merging_enabled: false
+    ttl: 3600
+```
+
+#### Read World Example
+
+A base that disables all email applied to all Zones
+
+```yaml
+providers:
+  spf-base:
+    class: octodns_spf.SpfSource
+```
+
+A follow on source that will add Google Workspace's recommended config
+
+```yaml
+providers:
+  spf-mail:
+    class: octodns_spf.SpfSource
+    includes:
+      - _spf.google.com
+      - _spf.salesforce.com
+    soft_fail: true
+    merging_enabled: true
+```
+
+Per https://support.google.com/a/answer/10684623?hl=en and
+https://help.salesforce.com/s/articleView?id=000382664&type=1
+
+Zones would have one or more of these providers added to their sources list
+
+```yaml
+zones:
+  ...
+
+  # main zone that will be generally used for email
+  github.com.:
+    sources:
+      - config
+      - spf-base
+      - spf-mail
+    targets:
+      ...
+
+  # ancilary zone, pretty much everything else
+  githubusercontent.com.:
+    sources:
+      - config
+      - spf-base
+    targets:
+      ...
+
+  ...
 ```
 
 ### Support Information
@@ -45,10 +124,6 @@ providers:
 
 TXT
 
-#### Dynamic
-
-SpfSource does not support dynamic records.
-
 ### Development
 
 See the [/script/](/script/) directory for some tools to help with the development process. They generally follow the [Script to rule them all](https://github.com/github/scripts-to-rule-them-all) pattern. Most useful is `./script/bootstrap` which will create a venv and install both the runtime and development related requirements. It will also hook up a pre-commit hook that covers most of what's run by CI.