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