Skip to content

Commit

Permalink
Pull request: all: add a changelog and a developer guide
Browse files Browse the repository at this point in the history
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
ainar-g committed Nov 13, 2020
1 parent 13f708b commit e802e66
Show file tree
Hide file tree
Showing 2 changed files with 164 additions and 0 deletions.
15 changes: 15 additions & 0 deletions CHANGELOG.md
@@ -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.
149 changes: 149 additions & 0 deletions HACKING.md
@@ -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

0 comments on commit e802e66

Please sign in to comment.