diff options
author | Evan Read <eread@gitlab.com> | 2022-10-26 01:30:08 +0300 |
---|---|---|
committer | Patrick Steinhardt <psteinhardt@gitlab.com> | 2022-10-27 09:43:53 +0300 |
commit | 1824a953bce1268269937a7a66684b642ebee505 (patch) | |
tree | febdc9dbec10bb67797d8a5f7a85650380876101 /STYLE.md | |
parent | 1977fb4f1fc1e379688e13b58050111f79b33e84 (diff) |
Add docs testing Make target and CI/CD joberead/add-docs-testing-make-target-and-ci_cd-job
Also expand reach of Markdown linting to more files
Diffstat (limited to 'STYLE.md')
-rw-r--r-- | STYLE.md | 58 |
1 files changed, 31 insertions, 27 deletions
@@ -14,7 +14,9 @@ code is accessible to different developers with varying setups. Use `%w` when wrapping errors with context. - fmt.Errorf("foo context: %w", err) +```go +fmt.Errorf("foo context: %w", err) +``` It allows to inspect the wrapped error by the caller with [`errors.As`](https://golang.org/pkg/errors/#As) and [`errors.Is`](https://golang.org/pkg/errors/#Is). More info about `errors` package capabilities could be found in the [blog post](https://blog.golang.org/go1.13-errors). @@ -24,11 +26,13 @@ It is customary in Go to pass errors up the call stack and decorate them. To be a good neighbor to the rest of the call stack we should keep our errors short. - // Good - fmt.Errorf("peek diff line: %w", err) +```go +// Good +fmt.Errorf("peek diff line: %w", err) - // Too long - fmt.Errorf("ParseDiffOutput: Unexpected error while peeking: %w", err) +// Too long +fmt.Errorf("ParseDiffOutput: Unexpected error while peeking: %w", err) +``` ### Use lower case in errors @@ -211,9 +215,9 @@ func testHelper(tb testing.TB, ctx context.Context) { We like table-driven tests ([Table-driven tests using subtests](https://blog.golang.org/subtests#TOC_4.), [Cheney blog post], [Golang wiki]). -- Use [subtests](https://blog.golang.org/subtests#TOC_4.) with your table-driven tests, using `t.Run`: +- Use [subtests](https://blog.golang.org/subtests#TOC_4.) with your table-driven tests, using `t.Run`: -``` +```go func TestTime(t *testing.T) { testCases := []struct { gmt string @@ -302,7 +306,7 @@ be implemented in a file called `testhelper_test.go` ## Git Commands -Gitaly relies heavily on spawning git subprocesses to perform work. Any git +Gitaly relies heavily on spawning Git subprocesses to perform work. Any Git commands spawned from Go code should use the constructs found in [`safecmd.go`](internal/git/safecmd.go). These constructs, all beginning with `Safe`, help prevent certain kinds of flag injection exploits. Proper usage is @@ -310,15 +314,15 @@ important to mitigate these injection risks: - When toggling an option, prefer a longer flag over a short flag for readability. - - Desired: `git.Flag{Name: "--long-flag"}` is easier to read and audit - - Undesired: `git.Flag{Name: "-L"}` + - Desired: `git.Flag{Name: "--long-flag"}` is easier to read and audit + - Undesired: `git.Flag{Name: "-L"}` - When providing a variable to configure a flag, make sure to include the variable after an equal sign - - Desired: `[]git.Flag{Name: "-a="+foo}` prevents flag injection - - Undesired: `[]git.Flag(Name: "-a"+foo)` allows flag injection + - Desired: `[]git.Flag{Name: "-a="+foo}` prevents flag injection + - Undesired: `[]git.Flag(Name: "-a"+foo)` allows flag injection - Always define a flag's name via a constant, never use a variable: - - Desired: `[]git.Flag{Name: "-a"}` - - Undesired: `[]git.Flag{Name: foo}` is ambiguous and difficult to audit + - Desired: `[]git.Flag{Name: "-a"}` + - Undesired: `[]git.Flag{Name: foo}` is ambiguous and difficult to audit ## Go Imports Style @@ -332,13 +336,13 @@ Example of **valid** usage: ```go import ( - "context" - "io" - "os/exec" + "context" + "io" + "os/exec" - "gitlab.com/gitlab-org/gitaly/internal/command" - "gitlab.com/gitlab-org/gitaly/internal/git/alternates" - "gitlab.com/gitlab-org/gitaly/internal/git/repository" + "gitlab.com/gitlab-org/gitaly/internal/command" + "gitlab.com/gitlab-org/gitaly/internal/git/alternates" + "gitlab.com/gitlab-org/gitaly/internal/git/repository" ) ``` @@ -346,15 +350,15 @@ Example of **invalid** usage: ```go import ( - "io" - "os/exec" + "io" + "os/exec" - "context" + "context" - "gitlab.com/gitlab-org/gitaly/internal/git/alternates" - "gitlab.com/gitlab-org/gitaly/internal/git/repository" + "gitlab.com/gitlab-org/gitaly/internal/git/alternates" + "gitlab.com/gitlab-org/gitaly/internal/git/repository" - "gitlab.com/gitlab-org/gitaly/internal/command" + "gitlab.com/gitlab-org/gitaly/internal/command" ) ``` @@ -398,7 +402,7 @@ func (scs SuperCoolService) MyAwesomeRPC(ctx context.Context, r Request) error { go func() { defer close(done) // signal when the goroutine returns - doWork(r) + doWork(r) }() return nil |