manager: some parts of documentation for version 6
Unfinished parts from this MR are tracked in #796.
Goal of this MR is to have a almost finished documentation for version 6. Parts that will not be finished should have a linked issue created by the time this is merged.
GitLab pages with documentation (probably, but not necessarily from this branch)
Step 1
-
getting started section -
rewrite pages about Lua configuration with declarative configuration -
syntax and conventions (this might be already rewritten somewhere) -
modules -
networking -
performance and resiliency -
policy, access control and data manipulation -
logging, monitoring, diagnostics -
DNSSEC, data verification -
experimental features
-
-
for developers section -
internal architecture
-
-
deployment guide -
manual -
systemd -
docker -
multiple instances
-
-
extending the resolver -
create gitlab issues for all documentation sections that won't be fully completed with this MR
Step 2
Merge request reports
Activity
changed milestone to %6.0.0
added manager label
added 1 commit
- b862208f - DROP: automatic installation to gitlab pages instead of manual
added 1 commit
- 07577eb6 - fixup! DROP: automatic installation to gitlab pages instead of manual
added 1 commit
- f8721fa3 - doc: upgrading-to-6 moved to developers chapter
added 2 commits
added 1 commit
- cc04e20b - fixup! doc: gettingstarted: some updates and changes
Resolved by Aleš MrázekI would like to discuss the usage of the term legacy config because I feel like it's somewhat insulting to the users using it.
The Cambridge dictionary says the following:
legacy something that is a part of your history or that remains from an earlier time:
"The Greeks have a rich legacy of literature." "The war has left a legacy of hatred."
Technically speaking, the naming is correct and there is nothing wrong with it. However, I feel that anything legacy related to code has a negative connotation. "Legacy code" is something I want to avoid. It's something I intend to shove into a box and never look at it again. It implies that you should stop using it. Is Lua configuration a legacy that we feel embarrassed of? Do we want to tell our users that they should move away as fast as possible?
I don't think so. I think that the Lua configuration is gonna stay with us pretty much forever. I would like to call Lua our "internal API" as it corresponds to internal design that is unlikely to change. I would try to tell users that anyone using it can expect things to be complicated, the abstractions leaky and backwards compatibility without any significant promises.
On the other hand, I don't have a nice alternative for "legacy config". "Advanced config" sounds like something the users should want to use, so that's also bad. Our usage of Lua reminds me of "intermediate representation" from compilers, but that's also not really precise. The best I came up with so far is to call it Lua configuration and write about it mostly in a section about internal architecture.
What are you opinions on this? It could as well be that I am wrong about the negative connotation with the word "legacy".
- Last reply by Vladimír Čunát
I tend to agree with @vsraier. I guess (internal) Lua configuration would be just fine.
added 1 commit
- d1741e89 - docs: attempt at improving overall structure of the documentation (reorg, no new text)
added 1 commit
- 4c880bcb - doc: initial drafts of internal architecture explainers
added 1 commit
- d298fceb - fixup! doc: initial drafts of internal architecture explainers
added 1 commit
- 8808a6d0 - doc: gettingstarted-config: config examples added
added 1 commit
- f487fd79 - fixup! doc: gettingstarted-config: config examples added
added 1 commit
- 80cd1e6a - doc: gettingstarted-config: config examples added
added 1 commit
- 40a58d11 - doc/architecture-gc.rst: describe how GC operates
added 1 commit
- 0d83bb1d - doc/README.md: update about requirements and building
added 1 commit
- bae1f05c - doc: deployment systemd and general structuring
mentioned in merge request !1395 (merged)
added 58 commits
-
a802d092...ab3111ff - 34 commits from branch
manager - ab3111ff...133d16df - 14 earlier commits
- cd471005 - doc: gettingstarted: minor modifications
- 1e9cc66e - fixup! doc: initial drafts of internal architecture explainers
- 6cfe97ad - doc: gettingstarted-config: config examples added
- 86cd8bc6 - doc/architecture-gc.rst: describe how GC operates
- c10af5d7 - doc/README.md: update about requirements and building
- f8f147c4 - Delete gettingstarted-intro.rst
- 53dc76f7 - doc: docker deployment
- 0689050c - doc: deployment systemd and general structuring
- 88708cf4 - doc: deployment: manual and fixes
- ab91dd38 - doc: deployment
Toggle commit list-
a802d092...ab3111ff - 34 commits from branch
added 1 commit
- 8f287a69 - manager: ignore false positive pylint errors
added 20 commits
- 8f287a69...8a504ce8 - 10 earlier commits
- 23b2dad9 - doc: gettingstarted: minor modifications
- b8cac707 - doc: gettingstarted-config: config examples added
- 63150cae - doc/architecture-gc.rst: describe how GC operates
- 9455c86c - doc/README.md: update about requirements and building
- 22f2e7ed - Delete gettingstarted-intro.rst
- 59eb68cb - doc: docker deployment
- c54ee419 - doc: deployment systemd and general structuring
- 67e4df6a - doc: deployment: manual and fixes
- e5862b05 - doc: deployment
- 2e587434 - manager: ignore false positive pylint errors
Toggle commit listmentioned in issue #796
