Draft: Backend docs #14840

ukleinek · 2024-11-11T16:21:36Z

Short description

Make the feature lists of all backend docs consistently list the same properties

I didn't know for all added fields what the right value is, added "???" in that case. Happy for feedback about how to change them into the right values.

Checklist

I have:

read the CONTRIBUTING.md document
compiled this code
tested this code
included documentation (including possible behaviour changes)
documented the code
added or modified regression test(s)
added or modified unit test(s)

docs/backends/random.rst

coveralls · 2024-11-11T16:47:03Z

Pull Request Test Coverage Report for Build 11813380634

Details

0 of 0 changed or added relevant lines in 0 files are covered.
98 unchanged lines in 13 files lost coverage.
Overall coverage decreased (-0.02%) to 64.668%

Files with Coverage Reduction	New Missed Lines	%
pdns/validate.cc	1	68.42%
pdns/sstuff.hh	2	56.83%
pdns/recursordist/lwres.cc	2	69.66%
pdns/iputils.cc	3	55.76%
pdns/stubresolver.cc	3	77.58%
pdns/packethandler.cc	3	73.4%
pdns/remote_logger.cc	3	53.81%
pdns/recursordist/rec-main.cc	3	62.32%
pdns/recursordist/test-syncres_cc1.cc	7	89.62%
pdns/recursordist/syncres.cc	10	79.28%

Totals
Change from base Build 11796572634:	-0.02%
Covered Lines:	125747
Relevant Lines:	163603

💛 - Coveralls

docs/backends/generic-postgresql.rst

Habbie

partial review

docs/backends/bind.rst

docs/backends/geoip.rst

ukleinek · 2024-11-12T10:27:10Z

The last push split out the change of itemize char from - to * into a separate commit to ease reviewing and I added the tense fix suggested by @jsoref in #14840 (comment).

ukleinek · 2024-11-12T10:56:11Z

Dropped Case: ...

Each backend that provides support for Primary also can do Autoprimary, so listing that separately isn't sensible. Before commit 45675c5 ("auth: catalog zone documentation") this column was titled "Super slave". Said commit then changed it wrongly to "Autoprimary". The right new term for "Super slave" is "Autosecondary". Adapt accordingly. Fixes: 45675c5 ("auth: catalog zone documentation")

Nearly all backend docs use * for their feature list. Upgrade that to "all".

Users shouldn't have to care about case handling and if a need is hit this is handled as a bug. So drop this documentation bit.

Make all the tables at the beginning of the backend detail descriptions describe the same properties in the same order. Stick to the order used in the overview table in index.rst. Also use the more politically correct names (i.e. Master -> Primary; Slave -> Secondary; Superslave -> Autosecondary).

For an event that happend at a definite time in the past, past simple is the right tense. Suggested-by: Josh Soref (josref)

ukleinek · 2024-11-13T08:36:14Z

The patch adding the "Autosecondary" column was replaced by a patch renaming the "Autoprimary" column to "Autosecondary". Also dropped "Autoprimary" from the individual backend docs. So the things to fix before this can go in are:

$ git grep '???' docs/backends/
docs/backends/geoip.rst:* API: ???
docs/backends/geoip.rst:* Multiple instances: ???
docs/backends/ldap.rst:* API: ???
docs/backends/ldap.rst:* Multiple instances: ???
docs/backends/lmdb.rst:* API: ???
docs/backends/lua2.rst:* API: ???
docs/backends/lua2.rst:* Multiple instances: ???
docs/backends/pipe.rst:* API: ???
docs/backends/pipe.rst:* Multiple instances: ???
docs/backends/random.rst:* API: ???
docs/backends/random.rst:* Multiple instances: ???
docs/backends/remote.rst:* API: ???
docs/backends/tinydns.rst:* Disabled data: ???
docs/backends/tinydns.rst:* Comments: ???
docs/backends/tinydns.rst:* API: ???

miodvallat

I believe I got these correct.

Also, all backend but Bind support multiple instances.

miodvallat · 2025-01-29T13:12:20Z

docs/backends/geoip.rst

 * DNSSEC: Yes
 * Disabled data: No
 * Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-only

miodvallat · 2025-01-29T13:21:21Z

docs/backends/ldap.rst

 * DNSSEC: No
 * Disabled data: No
 * Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-only

miodvallat · 2025-01-29T13:24:51Z

docs/backends/lmdb.rst

 * DNSSEC: Yes
 * Disabled data: Yes
 * Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-Write

miodvallat · 2025-01-29T13:25:56Z

docs/backends/lua2.rst

 * DNSSEC: Yes
 * Disabled data: No
 * Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-Write

miodvallat · 2025-01-29T13:26:25Z

docs/backends/pipe.rst

 * DNSSEC: Partial, no delegation, no key storage
 * Disabled data: No
 * Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-only

miodvallat · 2025-01-29T13:26:36Z

docs/backends/random.rst

+* DNSSEC: Yes, no key storage
+* Disabled data: No
+* Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-only

Not even close...

Suggested change

* API: ???

* API: No

miodvallat · 2025-01-29T13:26:56Z

docs/backends/remote.rst

-* Zone caching: Yes\*
+* Disabled data: No
+* Comments: No
+* API: ???


Suggested change

* API: ???

* API: Read-Write

miodvallat · 2025-01-29T13:27:19Z

docs/backends/tinydns.rst

+* DNSSEC: No
+* Disabled data: ???
+* Comments: ???
+* API: ???


Suggested change

* API: ???

* API: Read-only

miodvallat · 2025-01-29T13:27:26Z

docs/backends/tinydns.rst

+* DNS Update: No
+* DNSSEC: No
+* Disabled data: ???
+* Comments: ???


Suggested change

* Comments: ???

* Comments: No

miodvallat · 2025-01-29T13:29:31Z

docs/backends/tinydns.rst

+* Autosecondary: No
+* DNS Update: No
+* DNSSEC: No
+* Disabled data: ???


Suggested change

* Disabled data: ???

* Disabled data: No

mind04

Catch some low fruit. Review is probably incomplete.

mind04 · 2025-01-29T13:44:25Z

docs/backends/bind.rst

+* Producer: Yes
+* Consumer: Yes


Suggested change

* Producer: Yes

* Consumer: Yes

* Producer: No

* Consumer: No

mind04 · 2025-01-29T13:44:51Z

docs/backends/bind.rst

 * DNSSEC: Yes
 * Disabled data: No
 * Comments: No
 * API: Read-only
+* Multiple instances: No
 * Zone caching: Yes (except in hybrid mode)


Suggested change

* Zone caching: Yes (except in hybrid mode)

* Zone caching: Yes

mind04 · 2025-01-29T13:48:02Z

docs/backends/random.rst

+* Consumer: No
+* Autosecondary: No
+* DNS Update: No
+* DNSSEC: Yes, no key storage


Suggested change

* DNSSEC: Yes, no key storage

* DNSSEC: No

mind04 · 2025-01-29T13:50:09Z

docs/backends/random.rst

+* DNSSEC: Yes, no key storage
+* Disabled data: No
+* Comments: No
+* API: ???


Not even close...

Suggested change

* API: ???

* API: No

mind04 · 2025-01-29T13:51:11Z

docs/backends/random.rst

+* API: ???
+* Multiple instances: ???
+* Zone caching: No
+* Module name: built in


Suggested change

* Module name: built in

* Module name: random

mind04 · 2025-01-29T13:59:15Z

docs/backends/geoip.rst

+* Multiple instances: ???
 * Zone caching: Yes


Suggested change

* Multiple instances: ???

* Zone caching: Yes

* Multiple instances: Yes

* Zone caching: No

mind04 · 2025-01-29T14:01:40Z

docs/backends/lua2.rst

 * DNSSEC: Yes
 * Disabled data: No
 * Comments: No
+* API: ???
+* Multiple instances: ???
 * Zone caching: Yes


Suggested change

* Zone caching: Yes

* Zone caching: No

mind04 · 2025-01-29T14:02:29Z

docs/backends/pipe.rst

+* Producer: No
+* Consumer: No
+* Autosecondary: No
+* DNS Update: No
 * DNSSEC: Partial, no delegation, no key storage


Suggested change

* DNSSEC: Partial, no delegation, no key storage

* DNSSEC: No

jsoref reviewed Nov 11, 2024

View reviewed changes

docs/backends/random.rst Outdated Show resolved Hide resolved

zeha reviewed Nov 11, 2024

View reviewed changes

docs/backends/generic-postgresql.rst Outdated Show resolved Hide resolved

ukleinek force-pushed the backend-docs branch from 67c9833 to 3a78813 Compare November 11, 2024 21:31

Habbie requested changes Nov 12, 2024

View reviewed changes

docs/backends/bind.rst Outdated Show resolved Hide resolved

docs/backends/bind.rst Outdated Show resolved Hide resolved

docs/backends/geoip.rst Outdated Show resolved Hide resolved

Habbie added auth docs labels Nov 12, 2024

Habbie added this to the auth-5 milestone Nov 12, 2024

ukleinek force-pushed the backend-docs branch from 3a78813 to 6427d89 Compare November 12, 2024 10:25

ukleinek force-pushed the backend-docs branch 3 times, most recently from 6092180 to 268cf8d Compare November 12, 2024 10:55

ukleinek added 5 commits November 13, 2024 09:13

docs/backends: Use * consistently for the per backend feature list

147c678

Nearly all backend docs use * for their feature list. Upgrade that to "all".

docs/backends: Don't document Case handling

d3ec45e

Users shouldn't have to care about case handling and if a need is hit this is handled as a bug. So drop this documentation bit.

docs: random: Use the right tense

fd8d9d5

For an event that happend at a definite time in the past, past simple is the right tense. Suggested-by: Josh Soref (josref)

ukleinek force-pushed the backend-docs branch from 268cf8d to fd8d9d5 Compare November 13, 2024 08:27

miodvallat reviewed Jan 29, 2025

View reviewed changes

mind04 reviewed Jan 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Draft: Backend docs #14840

Draft: Backend docs #14840

ukleinek commented Nov 11, 2024

coveralls commented Nov 11, 2024 •

edited

Loading

Habbie left a comment

ukleinek commented Nov 12, 2024

ukleinek commented Nov 12, 2024

ukleinek commented Nov 13, 2024

miodvallat left a comment

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

mind04 Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

miodvallat Jan 29, 2025

mind04 left a comment

mind04 Jan 29, 2025

mind04 Jan 29, 2025

mind04 Jan 29, 2025

mind04 Jan 29, 2025

mind04 Jan 29, 2025

mind04 Jan 29, 2025

mind04 Jan 29, 2025

mind04 Jan 29, 2025

	* Zone caching: Yes (except in hybrid mode)
	* Zone caching: Yes

	* DNSSEC: Partial, no delegation, no key storage
	* DNSSEC: No

Draft: Backend docs #14840

Are you sure you want to change the base?

Draft: Backend docs #14840

Conversation

ukleinek commented Nov 11, 2024

Short description

Checklist

coveralls commented Nov 11, 2024 • edited Loading

Pull Request Test Coverage Report for Build 11813380634

Details

💛 - Coveralls

Habbie left a comment

Choose a reason for hiding this comment

ukleinek commented Nov 12, 2024

ukleinek commented Nov 12, 2024

ukleinek commented Nov 13, 2024

miodvallat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mind04 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Nov 11, 2024 •

edited

Loading