CONTRIBUTING.md

Contributing to Pilosa

The workflow components of these instructions apply to all Pilosa repositories.

Reporting a bug

If you have discovered a bug and don't see it in the github issue tracker, open a new issue.

Submitting a feature request

Feature requests are managed in Github issues, organized with Zenhub, which is publicly available as a browser extension. New features typically go through a Proposal Process which starts by opening a new issue that describes the new feature proposal.

Making code contributions

Before you start working on new features, you should open a new issue to let others know what you're doing, otherwise you run the risk of duplicating effort. This also gives others an opportunity to provide input for your feature.

If you want to help but you aren't sure where to start, check out our github label for low-effort issues.

Development Environment

• Ensure you have a recent version of Go installed. Pilosa generally supports the current and previous minor versions; check our CircleCI config file for the most up-to-date information.

• Make sure $GOPATH environment variable points to your Go working directory and $PATH incudes $GOPATH/bin, as described here.

• Fork the Pilosa repository to your own account.

• It will be easier to follow these instructions if you:

  export GH_USERNAME=<your github username>

• Create a directory (note that we use github.com/pilosa, NOT github.com/USER) and clone Pilosa:

  mkdir -p ${GOPATH}/src/github.com/pilosa && cd $_
  git clone https://github.com/pilosa/pilosa.git

• cd to your pilosa directory:

  cd ${GOPATH}/src/github.com/pilosa/pilosa

• Install Pilosa command line tools:

  make install

  Running pilosa should now run a Pilosa instance.

• The official Pilosa repository is your "origin" remote in git. Add your fork as your github username

  cd ${GOPATH}/src/github.com/pilosa/pilosa
  git remote add ${GH_USERNAME} git@github.com:${GH_USERNAME}/pilosa.git

Makefile

Pilosa includes a Makefile that automates several tasks:

• Install Pilosa:

  make install

• Install build dependencies:

  make install-build-deps

• Create the vendor directory:

  make vendor

• Run the test suite:

  make test

• View the coverage report:

  make cover-viz

• Clear the vendor/ and build/ directories:

  make clean

• Create release tarballs:

  make release

• Regenerate protocol buffer files in internal/:

  make generate-protoc

• Create tagged Docker image:

  make docker

• Run tests inside Docker container:

  make docker-test

Additional commands are available in the Makefile.

Submitting code changes

• Before starting to work on a task, sync your branch with the upstream:

  git checkout master
  git pull

• Create a local feature branch:

  git checkout -b something-amazing

• Commit your changes locally using git add and git commit. Please use appropriate commit messages.

• Make sure that you've written tests for your new feature, and then run the tests:

  make test

• Verify that your pull request is applied to the latest version of code on github:

  git checkout master
  git pull
  git checkout something-amazing
  git rebase master

• Push to your fork:

  git push -u $GH_USERNAME something-amazing:something-amazing

• Submit a pull request