1# Contributing to this project
2
3## Submitting bug reports and feature requests
4
5The LaunchDarkly SDK team monitors the [issue tracker](https://github.com/launchdarkly/go-jsonstream/issues) in tis repository. Bug reports and feature requests specific to this project should be filed in this issue tracker. The SDK team will respond to all newly filed issues within two business days.
6
7## Submitting pull requests
8
9We encourage pull requests and other contributions from the community. Before submitting pull requests, ensure that all temporary or unintended code is removed. Don't worry about adding reviewers to the pull request; the LaunchDarkly SDK team will add themselves. The SDK team will acknowledge all pull requests within two business days.
10
11## Build instructions
12
13### Prerequisites
14
15This project should be built against the lowest supported Go version as described in [README.md](./README.md).
16
17### Building
18
19To build the project without running any tests:
20```
21make
22```
23
24If you wish to clean your working directory between builds, you can clean it by running:
25```
26make clean
27```
28
29To run the linter:
30```
31make lint
32```
33
34### Testing
35
36To build and run all unit tests, for the default implementation and also the easyjson implementation:
37```
38make test
39make test-easyjson
40```
41
42To run benchmarks:
43```
44make benchmarks
45make benchmarks-easyjson
46```
47
48## Coding best practices
49
50### Test coverage
51
52It is important to keep unit test coverage as close to 100% as possible in this project. You can view the latest code coverage report in CircleCI, as `coverage.html` and `coverage.txt` in the artifacts. You can also generate this information locally with `make test-coverage`.
53
54The build will fail if there are any uncovered blocks of code, unless you explicitly add an override by placing a comment that starts with `// COVERAGE` somewhere within that block. Sometimes a gap in coverage is unavoidable, usually because the compiler requires us to provide a code path for some condition that in practice can't happen and can't be tested. Exclude these paths with a `// COVERAGE` comment.
55
56### Avoid heap allocations
57
58For performance and to avoid unwanted heap churn, it is highly desirable to avoid allocating data on the heap if it could instead be passed as a value type.
59
60Go's memory model uses a mix of stack and heap allocations, with the compiler transparently choosing the most appropriate strategy based on various type and scope rules. It is always preferable, when possible, to keep ephemeral values on the stack rather than on the heap to avoid creating extra work for the garbage collector.
61
62- The most obvious rule is that anything explicitly allocated by reference (`x := &SomeType{}`), or returned by reference (`return &x`), will be allocated on the heap. Avoid this unless the object has mutable state that must be shared.
63- Casting a value type to an interface causes it to be allocated on the heap, since an interface is really a combination of a type identifier and a hidden pointer.
64- A closure that references any variables outside of its scope (including the method receiver, if it is inside a method) causes an object to be allocated on the heap containing the values or addresses of those variables.
65- Treating a method as an anonymous function (`myFunc := someReceiver.SomeMethod`) is equivalent to a closure.
66
67Allocations are counted in the benchmark output: "5 allocs/op" means that a total of 5 heap objects were allocated during each run of the benchmark. This does not mean that the objects were retained, only that they were allocated at some point.
68
69For methods that should be guaranteed _not_ to do any heap allocations, the corresponding benchmarks should have names ending in `NoAlloc`. The `make benchmarks` target will automatically fail if allocations are detected in any benchmarks that have this name suffix.
View as plain text