1# Contributing
2
3## Getting Started
4
5Perkeep contributors regularly use Linux and macOS, and both are
6100% supported.
7
8Developing on Windows is sometimes broken, but should work. Let us
9know if we broke something, or we accidentally depend on some
10Unix-specific build tool somewhere.
11
12See https://perkeep.org/doc/contributing for information on how to
13contribute to the project and submit patches.
14
15See architecture docs: https://perkeep.org/doc/
16
17You can view docs for Perkeep packages with local godoc, or
18godoc.org.
19
20It's recommended you use git to fetch the source code, rather than
21hack from a Perkeep release's zip file:
22
23    $ git clone https://github.com/perkeep/perkeep.git perkeep.org
24
25On Debian/Ubuntu, some deps to get started:
26
27    $ sudo apt-get install libsqlite3-dev sqlite3 pkg-config git
28
29During development, rather than using the main binaries ("pk", "pk-put",
30"pk-get", "pk-mount", etc) directly, we instead use a wrapper (devcam)
31that automatically configures the environment to use the test server &
32test environment.
33
34## Building devcam
35
36We have a development tool to help with Perkeep development that's
37named `devcam` (for historical reasons: Perkeep used to be named
38Camlistore).
39
40To build devcam:
41
42    $ go run make.go
43
44And devcam will be in <pkroot>/bin/devcam.  You'll probably want to
45symlink it into your $PATH.
46
47Alternatively, if your Perkeep root is checked out at
48$GOPATH/src/perkeep.org (optional, but natural for Go users), you
49can just:
50
51    $ go install ./dev/devcam
52
53## Running devcam
54
55The subcommands of devcam start the server or run pk-put/pk-get/etc:
56
57    $ devcam server      # main server
58    $ devcam put         # pk-put
59    $ devcam get         # pk-get
60    $ devcam tool        # pk
61    $ devcam mount       # pk-mount
62
63Once the dev server is running,
64
65- Upload a file:
66
67      devcam put file ~/perkeep/COPYING
68
69- Create a permanode:
70
71      devcam put permanode
72
73- Use the UI: http://localhost:3179/ui/
74
75
76## Testing Patches
77
78Before submitting a patch, you should check that all the tests pass with:
79
80    $ devcam test
81
82You can use your usual git workflow to commit your changes, but for each
83change to be reviewed you should merge your commits into one before sending
84a GitHub Pull Request for review.
85
86## Commit Messages
87
88You should also try to write a meaningful commit message, which at least states
89in the first sentence what part or package of perkeep this commit is affecting.
90The following text should state what problem the change is addressing, and how.
91Finally, you should refer to the github issue(s) the commit is addressing, if any,
92and with the appropriate keyword if the commit is fixing the issue. (See
93https://help.github.com/articles/closing-issues-via-commit-messages/).
94
95For example:
96
97> pkg/search: add "file" predicate to search by file name
98>
99> File names were already indexed but there was no way to query the index for a file
100> by its name. The "file" predicate can now be used in search expressions (e.g. in the
101> search box of the web user interface) to achieve that.
102>
103> Fixes #10987
104
105## Vendored Code
106
107Changes to vendored third party code must be done using Go modules,
108using at least Go 1.12, but often requiring the Go 1.13 development
109tree.
110
111## Contributors
112
113We follow the Go convention for commits (messages) about new Contributors.
114See https://golang.org/doc/contribute.html#copyright , and examples such as
115https://perkeep.org/gw/85bf99a7, and https://perkeep.org/gw/8f9af410.
116
117## git Hooks
118
119You can optionally use our pre-commit hook so that your code gets gofmt'ed
120before being submitted (which should be done anyway).
121
122    $ devcam hook
123
124Please update this file as appropriate.
125