/
open-source.slide
71 lines (50 loc) · 2.28 KB
/
open-source.slide
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
Open Source Go Library Development
Things to Remember
18 Nov 2014
Kevin Gillette
@kevingillette
https://github.com/xtgo
https://github.com/xtblog/gotalks
* LICENSE
- Include a `LICENSE` file. Just do
- If you don't, nobody can or will use your library
- With some licenses, the file may be named `COPYING` (e.g. GPL)
- Consider license compatibility if you care about wide-spread adoption
- Consider license compatibility if you care about compliance
* README
- Include a `README` file, even if it only contains a `godoc.org` link
- Potential users may consider your package unready if it lacks a `README`
- GitHub, BitBucket, and others support a Markdown formatted `README.md`
- Focus on documenting the code; the README shouldn't be the primary reference
* Package Style & Documentation
- `gofmt` your code. Just do
- Plan to add a doc-comment to every exported function, type, and method
- If any of your code explicitly panics, document it
.link http://blog.golang.org/godoc-documenting-go-code
* godoc.org
- The best way to advertise your package
- To index your library, just visit `godoc.org/<your-import-path>`
- Works with anything go-gettable
* Dependencies
- Consider eliminating dependencies: large imports are unappealing
- Prefer stdlib imports: 3rd party packages don't usually have the same guarantees
* Testing & Sanity Checks
.link http://golang.org/pkg/testing/#example_B_RunParallel
- Example functions count as both tests and documentation
- If you use concurrency, test with the -race flag
- Run `go vet` at least once prior to publishing
- Use `go test -cover` to review test coverage; be wary of untested edge cases
- Use `golint` to make sure you're not making naming or documentation mistakes
.link http://blog.golang.org/cover
* Stability
- If your API is subject to change, mention it in the README
- Once your package is stable, don't break backwards compatibility
- If you need to break compatibility, host the new version under a different import path
* Miscellanea
- CI testing, coverage analysis, etc. are often free for open source projects
- Status badges are a popular to put in READMEs
- Don't use static badges to indicate that builds/tests pass
.link https://github.com/boltdb/bolt Badges Example
.link https://drone.io
.link https://coveralls.io
.link http://shields.io