-
Notifications
You must be signed in to change notification settings - Fork 2
/
contributing.html
145 lines (145 loc) · 6.54 KB
/
contributing.html
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
<!DOCTYPE html>
<html>
<head>
<title>Hockeypuck</title>
<link type="text/css" rel="stylesheet" href="static/article.css">
<meta charset='utf-8'>
</head>
<body>
<div id="topbar" class="wide">
<div class="container">
<div id="heading">Hockeypuck
OpenPGP Public Keyserver
</div>
</div>
</div>
<div id="page" class="wide">
<div class="container">
<div id="toc">
<ul>
<li><a href="#TOC_1.">Contributing</a></li>
<ul>
<li><a href="#TOC_1.1.">Where to contribute</a></li>
<ul>
<li><a href="#TOC_1.1.1.">Hockeypuck Packages</a></li>
<li><a href="#TOC_1.1.2.">Hockeypuck Server</a></li>
<li><a href="#TOC_1.1.3.">Hockeypuck Front-End</a></li>
<li><a href="#TOC_1.1.4.">Hockeypuck Packaging</a></li>
<li><a href="#TOC_1.1.5.">Hockeypuck documentation</a></li>
<li><a href="#TOC_1.1.6.">Hockeypuck testing</a></li>
</ul>
<li><a href="#TOC_1.2.">Tools</a></li>
<ul>
<li><a href="#TOC_1.2.1.">gopkg</a></li>
<li><a href="#TOC_1.2.2.">godeps</a></li>
<li><a href="#TOC_1.2.3.">Travis CI</a></li>
</ul>
<li><a href="#TOC_1.3.">Pull request guidelines</a></li>
</ul>
</ul>
</div>
<h1 id="TOC_1.">1. Contributing</h1>
<h2 id="TOC_1.1.">1.1. Where to contribute</h2>
<p>
Hockeypuck has been split into several Go package projects.
</p>
<p>
In general, all Hockeypuck projects are maintained under the
<a href="https://github.com/hockeypuck" target="_blank">hockeypuck</a> organization, in the following
Github projects:
</p>
<h3 id="TOC_1.1.1.">1.1.1. Hockeypuck Packages</h3>
<p>
Hockeypuck is composed of several small Go packages, each of which attempt to do one thing well.
</p>
<ul>
<li><a href="https://gopkg.in/hockeypuck/conflux.v2" target="_blank">conflux</a> Reconciliation protocol used for peering.</li>
<li><a href="https://gopkg.in/hockeypuck/hkp.v1" target="_blank">hkp</a> HKP protocol handler.</li>
<li><a href="https://gopkg.in/hockeypuck/openpgp.v1" target="_blank">openpgp</a> OpenPGP public key data model & processing. </li>
<li><a href="https://gopkg.in/hockeypuck/pghkp.v1" target="_blank">pghkp</a> PostgreSQL JSONB storage driver.</li>
</ul>
<h3 id="TOC_1.1.2.">1.1.2. Hockeypuck Server</h3>
<p>
The Hockeypuck server at <a href="https://github.com/hockeypuck/server" target="_blank">github.com/hockeypuck/server</a> integrates the
above packages with a server configuration model, logging, server and
maintenance utility binaries.
</p>
<h3 id="TOC_1.1.3.">1.1.3. Hockeypuck Front-End</h3>
<p>
<a href="https://github.com/hockeypuck/webroot" target="_blank">github.com/hockeypuck/webroot</a> is a fork of Matt Rude's
<a href="https://github.com/mattrude/pgpkeyserver-lite" target="_blank">pgpkeyserver-lite</a> front end.
It's included in the Hockeypuck release for convenience.
</p>
<h3 id="TOC_1.1.4.">1.1.4. Hockeypuck Packaging</h3>
<p>
<a href="https://github.com/hockeypuck/packaging" target="_blank">github.com/hockeypuck/packaging</a> is a collection of release management
scripts. These scripts fetch the above Hockeypuck source packages and all their
dependencies at known compatible and working versions. Debian packaging as well
as cross-compiled tarballs are supported for release distribution.
</p>
<h3 id="TOC_1.1.5.">1.1.5. Hockeypuck documentation</h3>
<p>
<a href="https://github.com/hockeypuck/hockeypuck" target="_blank">github.com/hockeypuck/hockeypuck</a> used to be the entire
Hockeypuck source tree, but since splitting up into separate package
projects, it is used primarily for project documentation.
</p>
<h3 id="TOC_1.1.6.">1.1.6. Hockeypuck testing</h3>
<p>
<a href="https://github.com/hockeypuck/testing" target="_blank">github.com/hockeypuck/testing</a> contains testdata used by some of the
other projects, such as OpenPGP key material examples used in
<a href="https://gopkg.in/hockeypuck/openpgp" target="_blank">openpgp</a> test cases. It also contains
<a href="http://docs.ansible.com/" target="_blank">Ansible</a> playbooks used to coordinate integration
tests. These might be a useful starting point for an Ansible-based deployment
of Hockeypuck.
</p>
<h2 id="TOC_1.2.">1.2. Tools</h2>
<h3 id="TOC_1.2.1.">1.2.1. gopkg</h3>
<p>
<a href="https://gopkg.in" target="_blank">gopkg.in</a> is used to version Hockeypuck APIs. This is a distinct concern
from dependency revision management. Versioned APIs provide certain guarantees
with regard to compatibility.
</p>
<h3 id="TOC_1.2.2.">1.2.2. godeps</h3>
<p>
The <a href="https://github.com/hockeypuck/server" target="_blank">server</a> releases use
<a href="https://launchpad.net/godeps" target="_blank">godeps</a> for managing
<a href="https://github.com/hockeypuck/server/blob/master/dependencies.tsv" target="_blank">package dependencies</a>.
I've tried several other dependency management solutions for Go
packages, and I find godeps to be simple, easy to work with and
well-maintained.
</p>
<h3 id="TOC_1.2.3.">1.2.3. Travis CI</h3>
<p>
Many of the Hockeypuck projects use <a href="https://travis-ci.org/hockeypuck" target="_blank">Travis CI</a> to build and test the projects on
commit. I've found Travis to be more useful than not for small, simple projects
with short tests. Which is really where you want to be. It's also nice to test
on many versions of Go, which is something I would not bother to do on every
commit otherwise.
</p>
<h2 id="TOC_1.3.">1.3. Pull request guidelines</h2>
<p>
Github pull requests will be reviewed on merit of relevance to the project
goals. Significant feature development should be discussed first on the
<a href="https://groups.google.com/forum/#!forum/hockeypuck-devel" target="_blank">mailing list</a>.
</p>
<p>
In code reviews, I'll look & ask for:
</p>
<ul>
<li>Correctness. Does it do what it claims to?</li>
<li>Succinct and appropriate naming.</li>
<li>General Go style (<a href="https://golang.org/doc/effective_go.html" target="_blank">Effective Go</a>, etc.) and codebase fit. When in doubt, ask.</li>
<li>Godoc comments on public symbols (an area I'd like to improve)</li>
<li>Adequate test coverage (ditto)</li>
</ul>
<h2>Authors</h2>
<div class="author">
<p>
Casey Marshall
</p>
<p class="link"><a href="https://hockeypuck.io/" target="_blank">https://hockeypuck.io/</a></p>
</div>
</div>
</div>
</body>
</html>