From c9d883daad089d29598b99f92e543d5ca111dc63 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Fri, 5 Feb 2021 18:36:37 +0300 Subject: [PATCH] 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 Date: Fri Feb 5 18:26:19 2021 +0300 all: imp docs, define more conventions --- CHANGELOG.md | 66 ++++++++++++++++++++++----------------------- HACKING.md | 76 ++++++++++++++++++++++++++++++++++------------------ 2 files changed, 82 insertions(+), 60 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e9da24ab..eac27727 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ and this project adheres to ## [Unreleased] ### 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 diff --git a/HACKING.md b/HACKING.md index 5e9e4e76..f3c42eb8 100644 --- a/HACKING.md +++ b/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) + + + +## Git * 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 - no *GitHub* issue. + GitHub issue you worked on in this branch) or just `fix-foo` if there was no + 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* +## Go > 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 + ### Code And Naming * 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 -[Linus said]: https://www.kernel.org/doc/html/v4.17/process/coding-style.html#indentation + ### Commenting - ### 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 + ### Formatting * 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 + ### Recommended Reading * . @@ -180,13 +193,24 @@ The rules are mostly sorted in the alphabetical order. * -## *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. +## Markdown -## 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. + +## Shell Scripting + + * 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 +## Text, Including Comments * 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* +## YAML * **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