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
This commit is contained in:
Ainar Garipov
parent
e84effffc3
commit
c9d883daad
66
CHANGELOG.md
66
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
|
||||
|
|
|
|||
76
HACKING.md
76
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
|
||||
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*
|
||||
## <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
|
||||
[Linus said]: https://www.kernel.org/doc/html/v4.17/process/coding-style.html#indentation
|
||||
### <a id="commenting" href="#commenting">Commenting</a>
|
||||
|
||||
### 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue