AdGuardHome/HACKING.md

425 lines
12 KiB
Markdown
Raw Normal View History

Pull request: all: add a new Makefile and scripts, remove goreleaaser Merge in DNS/adguard-home from 2276-releases to master Updates #2276. Squashed commit of the following: commit 84961947c51477aae53606ec6e2e0cce0bdfc139 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 30 14:36:13 2020 +0300 all: fix github build commit 54af2adbf2f433e80393fb142e66ba6b3a78b13e Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 30 14:34:02 2020 +0300 all: remove old Dockerfile, improve build scripts commit 99bb2f2ba1458d32074ac0911b5c02ce6669e43e Merge: 2292b677a 5e20ac7ed Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 30 13:47:19 2020 +0300 Merge branch 'master' into WIP-2276-releases commit 2292b677a20ce8e93d9e6e2bb042cd468606fec3 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Dec 30 13:30:10 2020 +0300 all: improve docker build commit 0bcc97c41f105ee4a4363f20fa4775c7643bf0cc Merge: c7d3f12ef aef4659e9 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Dec 29 17:47:45 2020 +0300 Merge branch 'master' into WIP-2276-releases commit c7d3f12ef2b63ddfa2acf46e3129fcbc56fb0a90 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Dec 29 16:28:25 2020 +0300 all: improve build scripts commit 55de1e5d7ef0fbdbd1a76cfb71362d16ca0a1966 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Dec 29 15:36:47 2020 +0300 all: fix Makefile commit d11b1fe28d0fde1efeaf6160a614951b19d0ef94 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Dec 29 14:16:19 2020 +0300 scripts: fix build-release commit ecc0577e2451afa86c37da7283a63a9d26fb37ba Merge: dde64ed8e 483f02c92 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Dec 29 13:59:32 2020 +0300 Merge branch 'master' into WIP-2276-releases commit dde64ed8e456f73559f21c2ca549dc3b46724add Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Fri Dec 25 18:04:46 2020 +0300 all: imp docs, other improvements commit be8574408db79901bb15c1d31916db3ca352a35f Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Fri Dec 25 14:48:30 2020 +0300 all: imp docker build commit fc1876f34b93d667bf166226f4bc666d394f10c7 Merge: fa5a304c8 955b735c8 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Fri Dec 25 13:54:29 2020 +0300 Merge branch 'master' into WIP-2276-releases commit fa5a304c83d86145796a2de4141de6d18f7c56bf Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 19:10:51 2020 +0300 all: improve scripts commit 3f32e3fd5e658d058d5c5172519384efc6cfef83 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 18:50:01 2020 +0300 all: improve scripts commit 2d38b81421acab4b90a7a19da7598c75063e8e93 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 18:25:21 2020 +0300 all: fix shell for windows, improve go-lint.sh commit d695285cd6dc476c0d972cfe0c49bbeea5f5a049 Merge: 313b020e9 9fb6bf82c Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 18:14:38 2020 +0300 Merge branch 'master' into WIP-2276-releases commit 313b020e9dfcdab736670cee72b2171eac8c32b7 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 18:13:31 2020 +0300 Makefile: use npm ci again commit 5acee9d6a6c8cd2a7dd04b173a73929650882bad Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 17:57:54 2020 +0300 all: try fixing windows build commit c63a2a54641ac8cd032a3306bb35e49b9ae74728 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 17:39:30 2020 +0300 all: imp scripts, try another goproxy and direct commit 423229e8b63ee73caeee8e84c23f67d145aff9df Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 24 17:25:29 2020 +0300 all: imp HACKING.md, try a new proxy ... and 1 more commit
2020-12-30 15:26:25 +00:00
# AdGuard Home Developer Guidelines
As of **March 2021**, following this document is obligatory for all new code.
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 and how to improve it.
The rules are mostly sorted in the alphabetical order.
## Contents
* [Git](#git)
* [Go](#go)
* [Code](#code)
* [Commenting](#commenting)
* [Formatting](#formatting)
* [Naming](#naming)
* [Testing](#testing)
* [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>
Pull request: 2305 limit message size Merge in DNS/adguard-home from 2305-limit-message-size to master Closes #2305. Squashed commit of the following: commit 6edd1e0521277a680f0053308efcf3d9cacc8e62 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 14:03:36 2020 +0300 aghio: fix final inaccuracies commit 4dd382aaf25132b31eb269749a2cd36daf0cb792 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:59:10 2020 +0300 all: improve code quality commit 060f923f6023d0e6f26441559b7023d5e5f96843 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:10:57 2020 +0300 aghio: add validation to constructor commit f57a2f596f5dc578548241c315c68dce7fc93905 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:19:26 2020 +0300 all: fix minor inaccuracies commit 93462c71725d3d00655a4bd565b77e64451fff60 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:13:23 2020 +0300 home: make test name follow convention commit 4922986ad84481b054479c43b4133a1b97bee86b Merge: 1f5472abc 046ec13fd Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:09:01 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 1f5472abcfa7427f389825fc59eb4253e1e2bfb7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:08:21 2020 +0300 aghio: improve readability commit 60dc706b093fa22bbf62f13b2341934364ddc4df Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 18:44:08 2020 +0300 home: cover middleware with test commit bedf436b947ca1fa4493af2fc94f1f40beec7c35 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 17:10:23 2020 +0300 aghio: improved error informativeness commit 682c5da9f21fa330fb3536bb1c112129c91b9990 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 13:37:51 2020 +0300 all: limit readers for ReadAll dealing with miscellanious data. commit 78c6dd8d90a0a43fe6ee3f9ed4d5fc637b15ba74 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 20:07:43 2020 +0300 all: handle ReadAll calls dealing with request's bodies. commit bfe1a6faf6468eb44515e2b0ecffa8c51f90b7e8 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 17:25:34 2020 +0300 home: add middlewares commit bbd1d491b318e6ba07f8af23ad546183383783a8 Merge: 7b77c2cad 62a8fe0b7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 16:44:04 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 7b77c2cad03154177392460982e1d73ee2a30177 Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Nov 17 15:33:33 2020 +0300 aghio: create package
2020-11-23 11:14:08 +00:00
* 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.
* Follow the commit message header format:
```none
pkg: fix the network error logging issue
```
Where `pkg` is the directory or Go package (without the `internal/` part)
where most changes took place. If there are several such packages, or the
change is top-level only, write `all`.
* Keep your commit messages, including headers, to eighty (**80**) columns.
* Only use lowercase letters in your commit message headers. The rest of the
message should follow the plain text conventions below.
Pull request: 2305 limit message size Merge in DNS/adguard-home from 2305-limit-message-size to master Closes #2305. Squashed commit of the following: commit 6edd1e0521277a680f0053308efcf3d9cacc8e62 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 14:03:36 2020 +0300 aghio: fix final inaccuracies commit 4dd382aaf25132b31eb269749a2cd36daf0cb792 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:59:10 2020 +0300 all: improve code quality commit 060f923f6023d0e6f26441559b7023d5e5f96843 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:10:57 2020 +0300 aghio: add validation to constructor commit f57a2f596f5dc578548241c315c68dce7fc93905 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:19:26 2020 +0300 all: fix minor inaccuracies commit 93462c71725d3d00655a4bd565b77e64451fff60 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:13:23 2020 +0300 home: make test name follow convention commit 4922986ad84481b054479c43b4133a1b97bee86b Merge: 1f5472abc 046ec13fd Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:09:01 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 1f5472abcfa7427f389825fc59eb4253e1e2bfb7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:08:21 2020 +0300 aghio: improve readability commit 60dc706b093fa22bbf62f13b2341934364ddc4df Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 18:44:08 2020 +0300 home: cover middleware with test commit bedf436b947ca1fa4493af2fc94f1f40beec7c35 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 17:10:23 2020 +0300 aghio: improved error informativeness commit 682c5da9f21fa330fb3536bb1c112129c91b9990 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 13:37:51 2020 +0300 all: limit readers for ReadAll dealing with miscellanious data. commit 78c6dd8d90a0a43fe6ee3f9ed4d5fc637b15ba74 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 20:07:43 2020 +0300 all: handle ReadAll calls dealing with request's bodies. commit bfe1a6faf6468eb44515e2b0ecffa8c51f90b7e8 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 17:25:34 2020 +0300 home: add middlewares commit bbd1d491b318e6ba07f8af23ad546183383783a8 Merge: 7b77c2cad 62a8fe0b7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 16:44:04 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 7b77c2cad03154177392460982e1d73ee2a30177 Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Nov 17 15:33:33 2020 +0300 aghio: create package
2020-11-23 11:14:08 +00:00
The only exceptions are direct mentions of identifiers from the source code
and filenames like `HACKING.md`.
## <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)
### <a id="code" href="#code">Code</a>
* Always `recover` from panics in new goroutines. Preferably in the very
first statement. If all you want there is a log message, use
`agherr.LogPanic`.
* Avoid `errors.New`, use `aghnet.Error` instead.
* Avoid `goto`.
Pull request: 2305 limit message size Merge in DNS/adguard-home from 2305-limit-message-size to master Closes #2305. Squashed commit of the following: commit 6edd1e0521277a680f0053308efcf3d9cacc8e62 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 14:03:36 2020 +0300 aghio: fix final inaccuracies commit 4dd382aaf25132b31eb269749a2cd36daf0cb792 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:59:10 2020 +0300 all: improve code quality commit 060f923f6023d0e6f26441559b7023d5e5f96843 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:10:57 2020 +0300 aghio: add validation to constructor commit f57a2f596f5dc578548241c315c68dce7fc93905 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:19:26 2020 +0300 all: fix minor inaccuracies commit 93462c71725d3d00655a4bd565b77e64451fff60 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:13:23 2020 +0300 home: make test name follow convention commit 4922986ad84481b054479c43b4133a1b97bee86b Merge: 1f5472abc 046ec13fd Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:09:01 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 1f5472abcfa7427f389825fc59eb4253e1e2bfb7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:08:21 2020 +0300 aghio: improve readability commit 60dc706b093fa22bbf62f13b2341934364ddc4df Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 18:44:08 2020 +0300 home: cover middleware with test commit bedf436b947ca1fa4493af2fc94f1f40beec7c35 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 17:10:23 2020 +0300 aghio: improved error informativeness commit 682c5da9f21fa330fb3536bb1c112129c91b9990 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 13:37:51 2020 +0300 all: limit readers for ReadAll dealing with miscellanious data. commit 78c6dd8d90a0a43fe6ee3f9ed4d5fc637b15ba74 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 20:07:43 2020 +0300 all: handle ReadAll calls dealing with request's bodies. commit bfe1a6faf6468eb44515e2b0ecffa8c51f90b7e8 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 17:25:34 2020 +0300 home: add middlewares commit bbd1d491b318e6ba07f8af23ad546183383783a8 Merge: 7b77c2cad 62a8fe0b7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 16:44:04 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 7b77c2cad03154177392460982e1d73ee2a30177 Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Nov 17 15:33:33 2020 +0300 aghio: create package
2020-11-23 11:14:08 +00:00
* Avoid `init` and use explicit initialization functions instead.
* Avoid `new`, especially with structs.
* Check against empty strings like this:
```go
if s == "" {
// …
}
```
Except when the check is done to then use the first character:
```go
if len(s) > 0 {
c := s[0]
}
```
* Constructors should validate their arguments and return meaningful errors.
As a corollary, avoid lazy initialization.
* Don't mix horizontal and vertical placement of arguments in function and
method calls. That is, either this:
```go
err := f(a, b, c)
```
Or, when the arguments are too long, this:
```go
err := functionWithALongName(
firstArgumentWithALongName,
secondArgumentWithALongName,
thirdArgumentWithALongName,
)
```
But **never** this:
```go
err := functionWithALongName(firstArgumentWithALongName,
secondArgumentWithALongName,
thirdArgumentWithALongName,
)
```
* Don't use `fmt.Sprintf` where a more structured approach to string
conversion could be used. For example, `net.JoinHostPort` or
`url.(*URL).String`.
Pull request: cover with tests Merge in DNS/adguard-home from 2271-cover-with-tests to master Updates #2271. Squashed commit of the following: commit db6440efe05171bc15367a2996521848ca348053 Merge: db7fa726b bf4c256c7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 19:23:09 2020 +0300 Merge branch 'master' into 2271-cover-with-tests commit db7fa726bb91b08ec7aaa6c0c818c88b5feb87cd Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 18:26:51 2020 +0300 all: clean dependencies sum commit b8dc6078c4bcc0de1b7e9073832de122f6fe38a4 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 16:46:00 2020 +0300 testutil: improve code quality commit 001b7194682b1f00aa54dc5a28236faed5a5b02d Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 16:29:49 2020 +0300 testutil: enhance functionality commit f6ccd91a4df6c56778eab8ae50e88e3818b20dd3 Merge: 43fa2eefb 6358240e9 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 15:57:37 2020 +0300 Merge branch 'master' into 2271-cover-with-tests commit 43fa2eefbc10ef361603cacc1ca12092b12a057a Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 14:55:15 2020 +0300 querylog: replace fake log with real in tests commit b95bee7565a14a02c80c78131b3ced224663dd8a Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 16 12:38:59 2020 +0300 dnsfilter: replace thoughtless declaration with idiomatic one commit a210b1586092e7ae91a9e67c972fa2d2f6baded6 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 13 19:00:25 2020 +0300 all: refresh golibs dependencies commit 4ff97bd1ade6c80e274ff5716e44df4eba55bdd9 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 13 18:38:47 2020 +0300 all: remove std log commit 542dbda10fefce9f46d15489712b163d919b1291 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 13 13:46:39 2020 +0300 querylog: improve test logic and readability commit 796d402385925e8e62a1b4c7bf56e4ceec22418c Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 12 19:06:42 2020 +0300 all: improve code quality commit e81894c11ef15b0453e8e5297f1349936a32f9dd Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 12 18:32:30 2020 +0300 all: cover with tests commit 252d81fc8a50a91b02cf0f6f35cc22178a2a4d90 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 12 17:32:01 2020 +0300 all: cover with tests
2020-11-16 16:45:31 +00:00
* Don't use naked `return`s.
Pull request: all: client id support Merge in DNS/adguard-home from 1383-client-id to master Updates #1383. Squashed commit of the following: commit ebe2678bfa9bf651a2cb1e64499b38edcf19a7ad Author: Ildar Kamalov <ik@adguard.com> Date: Wed Jan 27 17:51:59 2021 +0300 - client: check if IP is valid commit 0c330585a170ea149ee75e43dfa65211e057299c Author: Ildar Kamalov <ik@adguard.com> Date: Wed Jan 27 17:07:50 2021 +0300 - client: find clients by client_id commit 71c9593ee35d996846f061e114b7867c3aa3c978 Merge: 9104f161 3e9edd9e Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Jan 27 16:09:45 2021 +0300 Merge branch 'master' into 1383-client-id commit 9104f1615d2d462606c52017df25a422df872cea Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Jan 27 13:28:50 2021 +0300 dnsforward: imp tests commit ed47f26e611ade625a2cc2c2f71a291b796bbf8f Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Wed Jan 27 12:39:52 2021 +0300 dnsforward: fix address commit 98b222ba69a5d265f620c180c960d01c84a1fb3b Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 19:50:31 2021 +0300 home: imp code commit 4f3966548a2d8437d0b68207dd108dd1a6cb7d20 Merge: 199fdc05 c215b820 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 19:45:13 2021 +0300 Merge branch 'master' into 1383-client-id commit 199fdc056f8a8be5500584f3aaee32865188aedc Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 19:20:37 2021 +0300 all: imp tests, logging, etc commit 35ff14f4d534251aecb2ea60baba225f3eed8a3e Author: Ildar Kamalov <ik@adguard.com> Date: Tue Jan 26 18:55:19 2021 +0300 + client: remove block button from clients with client_id commit 32991a0b4c56583a02fb5e00bba95d96000bce20 Author: Ildar Kamalov <ik@adguard.com> Date: Tue Jan 26 18:54:25 2021 +0300 + client: add requests count for client_id commit 2d68df4d2eac4a296d7469923e601dad4575c1a1 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 15:49:50 2021 +0300 stats: handle client ids commit 4e14ab3590328f93a8cd6e9cbe1665baf74f220b Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 13:45:25 2021 +0300 openapi: fix example commit ca9cf3f744fe197cace2c28ddc5bc68f71dad1f3 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 13:37:10 2021 +0300 openapi: improve clients find api docs commit f79876e550c424558b704bc316a4cd04f25db011 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Tue Jan 26 13:18:52 2021 +0300 home: accept ids in clients find commit 5b72595122aa0bd64debadfd753ed8a0e0840629 Merge: 607e241f abf8f65f Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Mon Jan 25 18:34:56 2021 +0300 Merge branch 'master' into 1383-client-id commit 607e241f1c339dd6397218f70b8301e3de6a1ee0 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Mon Jan 25 18:30:39 2021 +0300 dnsforward: fix quic commit f046352fef93e46234c2bbe8ae316d21034260e5 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Mon Jan 25 16:53:09 2021 +0300 all: remove wildcard requirement commit 3b679489bae82c54177372be453fe184d8f0bab6 Author: Andrey Meshkov <am@adguard.com> Date: Mon Jan 25 16:02:28 2021 +0300 workDir now supports symlinks commit 0647ab4f113de2223f6949df001f42ecab05c995 Author: Ildar Kamalov <ik@adguard.com> Date: Mon Jan 25 14:59:46 2021 +0300 - client: remove wildcard from domain validation commit b1aec04a4ecadc9d65648ed6d284188fecce01c3 Author: Ildar Kamalov <ik@adguard.com> Date: Mon Jan 25 14:55:39 2021 +0300 + client: add form to download mobileconfig ... and 12 more commits
2021-01-27 15:32:13 +00:00
* Don't write non-test code with more than four (**4**) levels of indentation.
Just like [Linus said], plus an additional level for an occasional error
check or struct initialization.
The exception proving the rule is the table-driven test code, where an
additional level of indentation is allowed.
* Eschew external dependencies, including transitive, unless
absolutely necessary.
* Minimize scope of variables as much as possible.
Pull request: 2305 limit message size Merge in DNS/adguard-home from 2305-limit-message-size to master Closes #2305. Squashed commit of the following: commit 6edd1e0521277a680f0053308efcf3d9cacc8e62 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 14:03:36 2020 +0300 aghio: fix final inaccuracies commit 4dd382aaf25132b31eb269749a2cd36daf0cb792 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:59:10 2020 +0300 all: improve code quality commit 060f923f6023d0e6f26441559b7023d5e5f96843 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Nov 23 13:10:57 2020 +0300 aghio: add validation to constructor commit f57a2f596f5dc578548241c315c68dce7fc93905 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:19:26 2020 +0300 all: fix minor inaccuracies commit 93462c71725d3d00655a4bd565b77e64451fff60 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:13:23 2020 +0300 home: make test name follow convention commit 4922986ad84481b054479c43b4133a1b97bee86b Merge: 1f5472abc 046ec13fd Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:09:01 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 1f5472abcfa7427f389825fc59eb4253e1e2bfb7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 19:08:21 2020 +0300 aghio: improve readability commit 60dc706b093fa22bbf62f13b2341934364ddc4df Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 18:44:08 2020 +0300 home: cover middleware with test commit bedf436b947ca1fa4493af2fc94f1f40beec7c35 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 17:10:23 2020 +0300 aghio: improved error informativeness commit 682c5da9f21fa330fb3536bb1c112129c91b9990 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Nov 20 13:37:51 2020 +0300 all: limit readers for ReadAll dealing with miscellanious data. commit 78c6dd8d90a0a43fe6ee3f9ed4d5fc637b15ba74 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 20:07:43 2020 +0300 all: handle ReadAll calls dealing with request's bodies. commit bfe1a6faf6468eb44515e2b0ecffa8c51f90b7e8 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 17:25:34 2020 +0300 home: add middlewares commit bbd1d491b318e6ba07f8af23ad546183383783a8 Merge: 7b77c2cad 62a8fe0b7 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Nov 19 16:44:04 2020 +0300 Merge branch 'master' into 2305-limit-message-size commit 7b77c2cad03154177392460982e1d73ee2a30177 Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Nov 17 15:33:33 2020 +0300 aghio: create package
2020-11-23 11:14:08 +00:00
* No shadowing, since it can often lead to subtle bugs, especially with
errors.
* Prefer constants to variables where possible. Reduce global variables. Use
[constant errors] instead of `errors.New`.
* Prefer to use named functions for goroutines.
* Program code lines should not be longer than one hundred (**100**) columns.
For comments, see the text section below.
* Use linters. `make go-lint`.
* Write logs and error messages in lowercase only to make it easier to `grep`
logs and error messages without using the `-i` flag.
### <a id="commenting" href="#commenting">Commenting</a>
* See also the “[Text, Including Comments]” section below.
* Document everything, including unexported top-level identifiers, to build
a habit of writing documentation.
* Don't put identifiers into any kind of quotes.
* Put comments above the documented entity, **not** to the side, to improve
readability.
* When a method implements an interface, start the doc comment with the
standard template:
```go
// Foo implements the Fooer interface for *foo.
func (f *foo) Foo() {
// …
}
```
When the implemented interface is unexported:
```go
// Unwrap implements the hidden wrapper interface for *fooError.
func (err *fooError) Unwrap() (unwrapped error) {
// …
}
```
### <a id="formatting" href="#formatting">Formatting</a>
Pull request: 2704 local addresses vol.2 Merge in DNS/adguard-home from 2704-local-addresses-vol.2 to master Updates #2704. Updates #2829. Squashed commit of the following: commit 507d038c2709de59246fc0b65c3c4ab8e38d1990 Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 31 14:33:05 2021 +0300 aghtest: fix file name commit 8e19f99337bee1d88ad6595adb96f9bb23fa3c41 Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 31 14:06:43 2021 +0300 aghnet: rm redundant mutexes commit 361fa418b33ed160ca20862be1c455ab9378c03f Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 31 13:45:30 2021 +0300 all: fix names, docs commit 14034f4f0230d7aaa3645054946ae5c278089a99 Merge: 35e265cc a72ce1cf Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 31 13:38:15 2021 +0300 Merge branch 'master' into 2704-local-addresses-vol.2 commit 35e265cc8cd308ef1fda414b58c0217cb5f258e4 Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 31 13:33:35 2021 +0300 aghnet: imp naming commit 7a7edac7208a40697d7bc50682b923a144e28e2b Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Mar 30 20:59:54 2021 +0300 changelog: oops, nope yet commit d26a5d2513daf662ac92053b5e235189a64cc022 Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Mar 30 20:55:53 2021 +0300 all: some renaming for the glory of semantics commit 9937fa619452b0742616217b975e3ff048d58acb Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Mar 29 15:34:42 2021 +0300 all: log changes commit d8d9e6dfeea8474466ee25f27021efdd3ddb1592 Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Mar 26 18:32:23 2021 +0300 all: imp localresolver, imp cutting off own addresses commit 344140df449b85925f19b460fd7dc7c08e29c35a Author: Eugene Burkov <e.burkov@adguard.com> Date: Fri Mar 26 14:53:33 2021 +0300 all: imp code quality commit 1c5c0babec73b125044e23dd3aa75d8eefc19b28 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Mar 25 20:44:08 2021 +0300 all: fix go.mod commit 0b9fb3c2369a752e893af8ddc45a86bb9fb27ce5 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Mar 25 20:38:51 2021 +0300 all: add error handling commit a7a2e51f57fc6f8f74b95a264ad345cd2a9e026e Merge: c13be634 27f4f052 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Mar 25 19:48:36 2021 +0300 Merge branch 'master' into 2704-local-addresses-vol.2 commit c13be634f47bcaed9320a732a51c0e4752d0dad0 Author: Eugene Burkov <e.burkov@adguard.com> Date: Thu Mar 25 18:52:28 2021 +0300 all: cover rdns with tests, imp aghnet functionality commit 48bed9025944530c613ee53e7961d6d5fbabf8be Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 24 20:18:07 2021 +0300 home: make rdns great again commit 1dbacfc8d5b6895807797998317fe3cc814617c1 Author: Eugene Burkov <e.burkov@adguard.com> Date: Wed Mar 24 16:07:52 2021 +0300 all: imp external client restriction commit 1208a319a7f4ffe7b7fa8956f245d7a19437c0a4 Author: Eugene Burkov <e.burkov@adguard.com> Date: Mon Mar 22 15:26:45 2021 +0300 all: finish local ptr processor commit c8827fc3db289e1a5d7a11d057743bab39957b02 Author: Eugene Burkov <e.burkov@adguard.com> Date: Tue Mar 2 13:41:22 2021 +0300 all: imp ipdetector, add local ptr processor
2021-03-31 13:00:47 +01:00
* Decorate `break`, `continue`, `fallthrough`, `return`, and other function
exit points with empty lines unless it's the only statement in that block.
* Use `gofumpt --extra -s`.
* Write slices of struct like this:
```go
ts := []T{{
Field: Value0,
// …
}, {
Field: Value1,
// …
}, {
Field: Value2,
// …
}}
```
### <a id="naming" href="#naming">Naming</a>
* Don't use underscores in file and package names, unless they're build tags
or for tests. This is to prevent accidental build errors with weird tags.
* Name benchmarks and tests using the same convention as examples. For
example:
```go
func TestFunction(t *testing.T) { /* … */ }
func TestFunction_suffix(t *testing.T) { /* … */ }
func TestType_Method(t *testing.T) { /* … */ }
func TestType_Method_suffix(t *testing.T) { /* … */ }
```
* Name parameters in interface definitions:
```go
type Frobulator interface {
Frobulate(f Foo, b Bar) (r Result, err error)
}
```
* Name the deferred errors (e.g. when closing something) `derr`.
* Unused arguments in anonymous functions must be called `_`:
```go
v.onSuccess = func(_ int, msg string) {
// …
}
```
* Use named returns to improve readability of function signatures.
* When naming a file which defines an enitity, use singular nouns, unless the
entity is some form of a container for other entities:
```go
// File: client.go
package foo
type Client struct {
// …
}
```
```go
// File: clients.go
package foo
type Clients []*Client
// …
type ClientsWithCache struct {
// …
}
```
### <a id="testing" href="#testing">Testing</a>
* Use `assert.NoError` and `require.NoError` instead of `assert.Nil` and
`require.Nil` on errors.
* Use functions like `require.Foo` instead of `assert.Foo` when the test
cannot continue if the condition is false.
### <a id="recommended-reading" href="#recommended-reading">Recommended Reading</a>
* <https://github.com/golang/go/wiki/CodeReviewComments>.
* <https://github.com/golang/go/wiki/TestComments>.
* <https://go-proverbs.github.io/>
[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
## <a id="markdown" href="#markdown">Markdown</a>
* **TODO(a.garipov):** Define more Markdown conventions.
* 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.
* Put spaces within `$( cmd )`, `$(( expr ))`, and `{ cmd; }`.
* Put utility flags in the ASCII order and **don't** group them together. For
example, `ls -1 -A -q`.
* Script code lines should not be longer than one hundred (**100**) columns.
For comments, see the text section below.
* `snake_case`, not `camelCase` for variables. `kebab-case` for filenames.
* UPPERCASE names for external exported variables, lowercase for local,
unexported ones.
* Use `set -e -f -u` and also `set -x` in verbose mode.
* Use `readonly` liberally.
* Use the `"$var"` form instead of the `$var` form, unless word splitting is
required.
* When concatenating, always use the form with curly braces to prevent
accidental bad variable names. That is, `"${var}_tmp.txt"` and **not**
`"$var_tmp.txt"`. The latter will try to lookup variable `var_tmp`.
* When concatenating, surround the whole string with quotes. That is, use
this:
```sh
dir="${TOP_DIR}/sub"
```
And **not** this:
```sh
# Bad!
dir="${TOP_DIR}"/sub
```
* When using `test` (aka `[`), spell compound conditions with `&&`, `||`, and
`!` **outside** of `test` instead of `-a`, `-o`, and `!` inside of `test`
correspondingly. The latter ones are pretty much deprecated in POSIX.
See also: “[Problems With the `test` Builtin: What Does `-a` Mean?]”.
[Problems With the `test` Builtin: What Does `-a` Mean?]: https://www.oilshell.org/blog/2017/08/31.html
## <a id="text-including-comments" href="#text-including-comments">Text, Including Comments</a>
* End sentences with appropriate punctuation.
* Headers should be written with all initial letters capitalized, except for
references to variable names that start with a lowercase letter.
* Start sentences with a capital letter, unless the first word is a reference
to a variable name that starts with a lowercase letter.
* Text should wrap at eighty (**80**) columns to be more readable, to use
a common standard, and to allow editing or diffing side-by-side without
wrapping.
The only exception are long hyperlinks.
* Use U.S. English, as it is the most widely used variety of English in the
code right now as well as generally.
* Use double spacing between sentences to make sentence borders more clear.
* Use the serial comma (a.k.a. Oxford comma) to improve comprehension,
decrease ambiguity, and use a common standard.
* Write todos like this:
```go
// TODO(usr1): Fix the frobulation issue.
```
Or, if several people need to look at the code:
```go
// TODO(usr1, usr2): Fix the frobulation issue.
```
## <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.
* **TODO(a.garipov):** Find a YAML formatter or write our own.
* All strings, including keys, must be quoted. Reason: the “[NO-rway Law]”.
* Indent with two (**2**) spaces. YAML documents can get pretty
deeply-nested.
* No extra indentation in multiline arrays:
```yaml
'values':
- 'value-1'
- 'value-2'
- 'value-3'
```
* 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).
* Use `>` for multiline strings, unless you need to keep the line breaks. Use
`|` for multiline strings when you do.
[NO-rway Law]: https://news.ycombinator.com/item?id=17359376