How to contribute to the Cozy Stack?¶
Thank you for your interest in contributing to Cozy! There are many ways to contribute, and we appreciate all of them.
If you discover a security issue, please bring it to their attention right away! Please DO NOT file a public issue, instead send your report privately to security AT cozycloud DOT cc.
Security reports are greatly appreciated and we will publicly thank you for it. We currently do not offer a paid security bounty program, but are not ruling it out in the future.
While bugs are unfortunate, they’re a reality in software. We can’t fix what we don’t know about, so please report liberally. If you’re not sure if something is a bug or not, feel free to file a bug anyway.
Opening an issue is as easy as following this link and filling out the fields. Here are some things you can write about your bug:
- A short summary
- What did you try, step by step?
- What did you expect?
- What did happen instead?
- What is the version of the Cozy Stack?
You can also use the
cozy-stack tools bug command to
open the form to report issue prefilled with some useful system informations.
Pull requests are the primary mechanism we use to change Cozy. GitHub itself has some great documentation on using the Pull Request feature. We use the ‘fork and pull’ model described there.
Step 1: Fork¶
Fork the project on GitHub and check out your copy locally:
$ git clone https://github.com/cozy/cozy-stack.git
$ cd cozy-stack
$ git remote add fork git://github.com/username/cozy-stack.git
Step 2: Branch¶
Create a branch and start hacking:
$ git checkout -b my-branch -t origin/master
Step 3: Code¶
Well, I think you know how to do that. Just be sure to follow the coding guidelines from the Go community (gofmt, Effective Go, comment the code, etc.).
$ make lint
$ make jslint
Step 4: Test¶
Don’t forget to add tests and be sure they are green. You need CouchDB installed, with an account, and configuring the stack to use this account:
$ export COZY_COUCHDB_URL=http://admin:password@localhost:5984 $ make unit-tests
If you want to play with the modified cozy-stack (for example, testing it with a webapp), you can build it locally and start it with this command:
$ make run
Step 5: Commit¶
Writing good commit messages is important. A commit message should describe what changed and why.
Step 6: Rebase¶
git pull --rebase, or
git rebase (but not
git merge), to sync your
work from time to time:
$ git pull origin master --rebase
Step 7: Push¶
$ git push fork my-branch
Go to https://github.com/username/cozy-stack and select your branch. Click the ‘Pull Request’ button and fill out the form.
Pull requests are usually reviewed within a few days. If there are comments to address, apply your changes in a separate commit and push that to your branch.
The codebase of cozy-stack contains several packages, and it is quite easy to have circular import issues in go. To limit the risk, we have split the packages in several directories with some rules for the imports. In short, a package in this list should import other packages that are on the same line or below:
cmdare the top level packages
webis where we have the routers and handlers for web requests
workeris where we define the workers for our job system
modelis for high-level internal packages (in general one package is used for one doctype)
clientis a small number of packages used for writing clients for the stack
pkgis the low-level packages (most of those packages are just a couple of structs and functions).
tests/testutils can be used safely in
model, it can be used but it is recommended to use a fake package for the
tests if it is the case. For example,
model/oauth/client_test.go is declared
The cozy-stack serve some assets for the client application. In particular,
cozy-client-js and cozy-bar assets are listed in
assets/.externals. To update
them, you can open a pull request for this file. When a maintainer will accept
this pull request, he will also run
make assets to transform them in go code
(to make the repository go gettable).
There are some useful commands to know in order to develop with the go code of cozy-stack:
cd cozy-stack make help # Show the commands that can be launched via make go build # Build the stack, also takes care of updating dependencies through gomodules go install # Installs the `cozy-stack` binary go test -v ./... # To launch the tests go run main.go serve # To start the API server godoc -http=:6060 # To start the documentation server # Open http://127.0.0.1:6060/pkg/github.com/cozy/cozy-stack/
Documentation improvements are very welcome. We try to keep a good documentation
docs/ folder. But, you know, we are developers, we can forget to
document important stuff that look obvious to us. And documentation can always
The translations are kept synchronized with transifex via their github integration.
You can help us by making our community even more vibrant. For example, you can write a blog post, take some videos, answer the questions on the forum, organize new meetups, and speak about what you like in Cozy!