Pull request: all: imp docs, define more conventions

Merge in DNS/adguard-home from imp-md to master

Squashed commit of the following:

commit bb3eba8b248c644672b48c7ccfa206b620dfb0a0
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Fri Feb 5 18:26:19 2021 +0300

    all: imp docs, define more conventions

CHANGELOG.md

@@ -10,7 +10,7 @@ and this project adheres to
 ## [Unreleased]
 
 <!--
-## [v0.105.0] - 2021-02-03
+## [v0.105.0] - 2021-02-08
 -->
 
 ### Added
@@ -30,17 +30,6 @@ and this project adheres to
 - `$dnstype` modifier for filters ([#2337]).
 - HTTP API request body size limit ([#2305]).
 
-[#1361]: https://github.com/AdguardTeam/AdGuardHome/issues/1361
-[#1383]: https://github.com/AdguardTeam/AdGuardHome/issues/1383
-[#2102]: https://github.com/AdguardTeam/AdGuardHome/issues/2102
-[#2179]: https://github.com/AdguardTeam/AdGuardHome/issues/2179
-[#2224]: https://github.com/AdguardTeam/AdGuardHome/issues/2224
-[#2302]: https://github.com/AdguardTeam/AdGuardHome/issues/2302
-[#2304]: https://github.com/AdguardTeam/AdGuardHome/issues/2304
-[#2305]: https://github.com/AdguardTeam/AdGuardHome/issues/2305
-[#2337]: https://github.com/AdguardTeam/AdGuardHome/issues/2337
-[#2401]: https://github.com/AdguardTeam/AdGuardHome/issues/2401
-
 ### Changed
 
 - `Access-Control-Allow-Origin` is now only set to the same origin as the
@@ -60,20 +49,6 @@ and this project adheres to
 - New build system and various internal improvements ([#2271], [#2276], [#2297],
   [#2509], [#2552]).
 
-[#2231]: https://github.com/AdguardTeam/AdGuardHome/issues/2231
-[#2271]: https://github.com/AdguardTeam/AdGuardHome/issues/2271
-[#2276]: https://github.com/AdguardTeam/AdGuardHome/issues/2276
-[#2297]: https://github.com/AdguardTeam/AdGuardHome/issues/2297
-[#2306]: https://github.com/AdguardTeam/AdGuardHome/issues/2306
-[#2343]: https://github.com/AdguardTeam/AdGuardHome/issues/2343
-[#2358]: https://github.com/AdguardTeam/AdGuardHome/issues/2358
-[#2391]: https://github.com/AdguardTeam/AdGuardHome/issues/2391
-[#2394]: https://github.com/AdguardTeam/AdGuardHome/issues/2394
-[#2484]: https://github.com/AdguardTeam/AdGuardHome/issues/2484
-[#2509]: https://github.com/AdguardTeam/AdGuardHome/issues/2509
-[#2552]: https://github.com/AdguardTeam/AdGuardHome/issues/2552
-[#2589]: https://github.com/AdguardTeam/AdGuardHome/issues/2589
-
 ### Deprecated
 
 - Go 1.14 support.  v0.106.0 will require at least Go 1.15 to build.
@@ -93,14 +68,6 @@ and this project adheres to
 - Incorrect detection of the IPv6 address of an interface as well as another
   infinite loop in the `/dhcp/find_active_dhcp` HTTP API ([#2355]).
 
-[#2225]: https://github.com/AdguardTeam/AdGuardHome/issues/2225
-[#2293]: https://github.com/AdguardTeam/AdGuardHome/issues/2293
-[#2345]: https://github.com/AdguardTeam/AdGuardHome/issues/2345
-[#2355]: https://github.com/AdguardTeam/AdGuardHome/issues/2355
-[#2459]: https://github.com/AdguardTeam/AdGuardHome/issues/2459
-[#2508]: https://github.com/AdguardTeam/AdGuardHome/issues/2508
-[#2630]: https://github.com/AdguardTeam/AdGuardHome/issues/2630
-
 ### Removed
 
 - The undocumented ability to use hostnames as any of `bind_host` values in
@@ -110,6 +77,37 @@ and this project adheres to
   `scripts/make/build-docker.sh` which uses `scripts/make/Dockerfile`.
 - Support for pre-v0.99.3 format of query logs ([#2102]).
 
+[#1361]: https://github.com/AdguardTeam/AdGuardHome/issues/1361
+[#1383]: https://github.com/AdguardTeam/AdGuardHome/issues/1383
+[#2102]: https://github.com/AdguardTeam/AdGuardHome/issues/2102
+[#2179]: https://github.com/AdguardTeam/AdGuardHome/issues/2179
+[#2224]: https://github.com/AdguardTeam/AdGuardHome/issues/2224
+[#2225]: https://github.com/AdguardTeam/AdGuardHome/issues/2225
+[#2231]: https://github.com/AdguardTeam/AdGuardHome/issues/2231
+[#2271]: https://github.com/AdguardTeam/AdGuardHome/issues/2271
+[#2276]: https://github.com/AdguardTeam/AdGuardHome/issues/2276
+[#2293]: https://github.com/AdguardTeam/AdGuardHome/issues/2293
+[#2297]: https://github.com/AdguardTeam/AdGuardHome/issues/2297
+[#2302]: https://github.com/AdguardTeam/AdGuardHome/issues/2302
+[#2304]: https://github.com/AdguardTeam/AdGuardHome/issues/2304
+[#2305]: https://github.com/AdguardTeam/AdGuardHome/issues/2305
+[#2306]: https://github.com/AdguardTeam/AdGuardHome/issues/2306
+[#2337]: https://github.com/AdguardTeam/AdGuardHome/issues/2337
+[#2343]: https://github.com/AdguardTeam/AdGuardHome/issues/2343
+[#2345]: https://github.com/AdguardTeam/AdGuardHome/issues/2345
+[#2355]: https://github.com/AdguardTeam/AdGuardHome/issues/2355
+[#2358]: https://github.com/AdguardTeam/AdGuardHome/issues/2358
+[#2391]: https://github.com/AdguardTeam/AdGuardHome/issues/2391
+[#2394]: https://github.com/AdguardTeam/AdGuardHome/issues/2394
+[#2401]: https://github.com/AdguardTeam/AdGuardHome/issues/2401
+[#2459]: https://github.com/AdguardTeam/AdGuardHome/issues/2459
+[#2484]: https://github.com/AdguardTeam/AdGuardHome/issues/2484
+[#2508]: https://github.com/AdguardTeam/AdGuardHome/issues/2508
+[#2509]: https://github.com/AdguardTeam/AdGuardHome/issues/2509
+[#2552]: https://github.com/AdguardTeam/AdGuardHome/issues/2552
+[#2589]: https://github.com/AdguardTeam/AdGuardHome/issues/2589
+[#2630]: https://github.com/AdguardTeam/AdGuardHome/issues/2630
+
 ## [v0.104.3] - 2020-11-19
 
 ### Fixed

HACKING.md

@@ -1,17 +1,33 @@
  #  AdGuard Home Developer Guidelines
 
-As of **December 2020**, this document is partially a work-in-progress, but
+As of **February 2021**, this document is partially a work-in-progress, but
 should still be followed.  Some of the rules aren't enforced as thoroughly or
 remain broken in old code, but this is still the place to find out about what we
 **want** our code to look like.
 
 The rules are mostly sorted in the alphabetical order.
 
-##  *Git*
+## Contents
+
+ *  [Git](#git)
+ *  [Go](#go)
+     *  [Code And Naming](#code-and-naming)
+     *  [Commenting](#commenting)
+     *  [Formatting](#formatting)
+     *  [Recommended Reading](#recommended-reading)
+ *  [Markdown](#markdown)
+ *  [Shell Scripting](#shell-scripting)
+ *  [Text, Including Comments](#text-including-comments)
+ *  [YAML](#yaml)
+
+<!-- NOTE: Use the IDs that GitHub would generate in order for this to work both
+on GitHub and most other Markdown renderers. -->
+
+##  <a id="git" href="#git">Git</a>
 
  *  Call your branches either `NNNN-fix-foo` (where `NNNN` is the ID of the
-    *GitHub* issue you worked on in this branch) or just `fix-foo` if there was
+    GitHub issue you worked on in this branch) or just `fix-foo` if there was no
-    no *GitHub* issue.
+    GitHub issue.
 
  *  Follow the commit message header format:
 
@@ -31,14 +47,14 @@ The rules are mostly sorted in the alphabetical order.
     The only exceptions are direct mentions of identifiers from the source code
     and filenames like `HACKING.md`.
 
-##  *Go*
+##  <a id="go" href="#go">Go</a>
 
 > Not Golang, not GO, not GOLANG, not GoLang. It is Go in natural language,
 > golang for others.
 
 — [@rakyll](https://twitter.com/rakyll/status/1229850223184269312)
 
- ###  Code And Naming
+ ###  <a id="code-and-naming" href="#code-and-naming">Code And Naming</a>
 
  *  Avoid `goto`.
 
@@ -116,12 +132,9 @@ The rules are mostly sorted in the alphabetical order.
  *  Write logs and error messages in lowercase only to make it easier to `grep`
     logs and error messages without using the `-i` flag.
 
-[constant errors]: https://dave.cheney.net/2016/04/07/constant-errors
+ ###  <a id="commenting" href="#commenting">Commenting</a>
-[Linus said]:      https://www.kernel.org/doc/html/v4.17/process/coding-style.html#indentation
 
- ###  Commenting
+ *  See also the “[Text, Including Comments]” section below.
-
- *  See also the *Text, Including Comments* section below.
 
  *  Document everything, including unexported top-level identifiers, to build
     a habit of writing documentation.
@@ -150,7 +163,7 @@ The rules are mostly sorted in the alphabetical order.
     }
     ```
 
- ###  Formatting
+ ###  <a id="formatting" href="#formatting">Formatting</a>
 
  *  Add an empty line before `break`, `continue`, `fallthrough`, and `return`,
     unless it's the only statement in that block.
@@ -172,7 +185,7 @@ The rules are mostly sorted in the alphabetical order.
     }}
     ```
 
- ###  Recommended Reading
+ ###  <a id="recommended-reading" href="#recommended-reading">Recommended Reading</a>
 
  *  <https://github.com/golang/go/wiki/CodeReviewComments>.
 
@@ -180,13 +193,24 @@ The rules are mostly sorted in the alphabetical order.
 
  *  <https://go-proverbs.github.io/>
 
-##  *Markdown*
+[constant errors]:          https://dave.cheney.net/2016/04/07/constant-errors
+[Linus said]:               https://www.kernel.org/doc/html/v4.17/process/coding-style.html#indentation
+[Text, Including Comments]: #text-including-comments
 
- *  **TODO(a.garipov):** Define our *Markdown* conventions.
+##  <a id="markdown" href="#markdown">Markdown</a>
 
-##  Shell Scripting
+ *  **TODO(a.garipov):** Define more Markdown conventions.
 
- *  Avoid bashisms and GNUisms, prefer *POSIX* features only.
+ *  Prefer triple-backtick preformatted code blocks to indented code blocks.
+
+ *  Use asterisks and not underscores for bold and italic.
+
+ *  Use either link references or link destinations only.  Put all link
+    reference definitions at the end of the second-level block.
+
+##  <a id="shell-scripting" href="#shell-scripting">Shell Scripting</a>
+
+ *  Avoid bashisms and GNUisms, prefer POSIX features only.
 
  *  Prefer `'raw strings'` to `"double quoted strings"` whenever possible.
 
@@ -225,7 +249,7 @@ The rules are mostly sorted in the alphabetical order.
     dir="${TOP_DIR}"/sub
     ```
 
-##  Text, Including Comments
+##  <a id="text-including-comments" href="#text-including-comments">Text, Including Comments</a>
 
  *  End sentences with appropriate punctuation.
 
@@ -246,7 +270,7 @@ The rules are mostly sorted in the alphabetical order.
 
  *  Use double spacing between sentences to make sentence borders more clear.
 
- *  Use the serial comma (a.k.a. *Oxford* comma) to improve comprehension,
+ *  Use the serial comma (a.k.a. Oxford comma) to improve comprehension,
     decrease ambiguity, and use a common standard.
 
  *  Write todos like this:
@@ -261,16 +285,16 @@ The rules are mostly sorted in the alphabetical order.
     // TODO(usr1, usr2): Fix the frobulation issue.
     ```
 
-##  *YAML*
+##  <a id="yaml" href="#yaml">YAML</a>
 
  *  **TODO(a.garipov):** Define naming conventions for schema names in our
-    *OpenAPI* *YAML* file.  And just generally OpenAPI conventions.
+    OpenAPI YAML file.  And just generally OpenAPI conventions.
 
- *  **TODO(a.garipov):** Find a *YAML* formatter or write our own.
+ *  **TODO(a.garipov):** Find a YAML formatter or write our own.
 
- *  All strings, including keys, must be quoted.  Reason: the [*NO-rway Law*].
+ *  All strings, including keys, must be quoted.  Reason: the “[NO-rway Law]”.
 
- *  Indent with two (**2**) spaces.  *YAML* documents can get pretty
+ *  Indent with two (**2**) spaces.  YAML documents can get pretty
     deeply-nested.
 
  *  No extra indentation in multiline arrays:
@@ -284,8 +308,8 @@ The rules are mostly sorted in the alphabetical order.
 
  *  Prefer single quotes for strings to prevent accidental escaping, unless
     escaping is required or there are single quotes inside the string (e.g. for
-    *GitHub Actions*).
+    GitHub Actions).
 
  *  Use `>` for multiline strings, unless you need to keep the line breaks.
 
-[*NO-rway Law*]: https://news.ycombinator.com/item?id=17359376
+[NO-rway Law]: https://news.ycombinator.com/item?id=17359376