-
Notifications
You must be signed in to change notification settings - Fork 1.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Pull request: all: add a changelog and a developer guide
Merge in DNS/adguard-home from 2294-changelog to master Closes #2294. Squashed commit of the following: commit 25ffc97 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Nov 12 19:40:48 2020 +0300 all: add a changelog and a developer guide
- Loading branch information
Showing
2 changed files
with
164 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
# AdGuard Home Changelog | ||
|
||
All notable changes to this project will be documented in this file. | ||
|
||
The format is based on | ||
[*Keep a Changelog*](https://keepachangelog.com/en/1.0.0/), | ||
and this project adheres to | ||
[Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
||
## [Unreleased] | ||
|
||
### Added | ||
|
||
- This changelog :-) (#2294). | ||
- `HACKING.md`, a guide for developers. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,149 @@ | ||
# AdGuardHome Developer Guidelines | ||
|
||
As of **2020-11-12**, this document is still a work-in-progress. Some of the | ||
rules aren't enforced, and others might change. Still, this is a good place to | ||
find out about how we **want** our code to look like. | ||
|
||
## Git | ||
|
||
* Follow the commit message header format: | ||
|
||
```none | ||
pkg: fix the network error logging issue | ||
``` | ||
Where `pkg` is the package where most changes took place. If there are | ||
several such packages, just write `all`. | ||
* Keep your commit messages to be no wider than eighty (**80**) columns. | ||
* Only use lowercase letters in your commit message headers. | ||
## Go | ||
* <https://github.com/golang/go/wiki/CodeReviewComments>. | ||
* <https://github.com/golang/go/wiki/TestComments>. | ||
* <https://go-proverbs.github.io/> | ||
* Avoid `init` and use explicit initialization functions instead. | ||
* Avoid `new`, especially with structs. | ||
* Document everything, including unexported top-level identifiers, to build | ||
a habit of writing documentation. | ||
* 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. | ||
* Don't write 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. | ||
* Eschew external dependencies, including transitive, unless | ||
absolutely necessary. | ||
* No `goto`. | ||
* 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`. | ||
* Put comments above the documented entity, **not** to the side, to improve | ||
readability. | ||
* Use `gofumpt --extra -s`. | ||
**TODO(a.garipov):** Add to the linters. | ||
* Use linters. | ||
* Use named returns to improve readability of function signatures. | ||
* 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() { | ||
// … | ||
} | ||
``` | ||
* Write logs and error messages in lowercase only to make it easier to `grep` | ||
logs and error messages without using the `-i` flag. | ||
* Write slices of struct like this: | ||
```go | ||
ts := []T{{ | ||
Field: Value0, | ||
// … | ||
}, { | ||
Field: Value1, | ||
// … | ||
}, { | ||
Field: Value2, | ||
// … | ||
}} | ||
``` | ||
[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 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. | ||
``` | ||
## Markdown | ||
* **TODO(a.garipov):** Define our Markdown conventions. | ||
## YAML | ||
* **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. | ||
* No extra indentation in multiline arrays: | ||
```yaml | ||
'values': | ||
- 'value-1' | ||
- 'value-2' | ||
- 'value-3' | ||
``` | ||
* Prefer single quotes for string to prevent accidental escaping, unless | ||
escaping is required. | ||
[NO-rway Law]: https://news.ycombinator.com/item?id=17359376 |