Skip to content

Latest commit

 

History

History
204 lines (141 loc) · 6.55 KB

CONTRIBUTING.md

File metadata and controls

204 lines (141 loc) · 6.55 KB
Raw

How to Contribute

We'd love to get patches from you!

Getting Started

Prerequisites

To compile Voyager from scratch, the following packages will need to be installed:

  • Python 3.7 or higher.
  • A C++ compiler, e.g. gcc, clang, etc.

Building Voyager

git clone [email protected]:spotify/voyager.git
cd voyager
pip3 install -r python/dev-requirements.txt
pip3 install .

To compile a debug build of voyager that allows using a debugger (like gdb or lldb), use the following command to build the package locally and install a symbolic link for debugging:

cd python
DEBUG=1 python3 setup.py build develop

Then, you can import voyager from Python (or run the tests with tox) to test out your local changes.

If you're on macOS or Linux, you can try to compile a debug build faster by using Ccache:

macOS

brew install ccache
rm -rf build && CC="ccache clang" CXX="ccache clang++" DEBUG=1 python3 -j8 -m pip install -e .

Linux

e.g.

sudo yum install ccache  # or apt, if on a Debian

# If using GCC:
rm -rf build && CC="ccache gcc" CXX="scripts/ccache_g++" DEBUG=1 python3 setup.py build -j8 develop

# ...or if using Clang:
rm -rf build && CC="ccache clang" CXX="scripts/ccache_clang++" DEBUG=1 python3 setup.py build -j8 develop

Updating Documentation

If you notice that the documentation is out of date, feel free to run these commands in order to update the docs and make a PR with the changes.

Python

While voyager is mostly C++ code, it ships with .pyi files to allow for type hints in text editors and via MyPy. To update the Python type hint files, use the following commands:

cd python
python3 -m scripts.generate_type_stubs_and_docs
# Documentation will be dumped into ../docs/python/

Java

To update the javadocs for the java bindings, you can simply run:

cd java
mvn package

this will update the java documentation located in docs/java/.

Workflow

We follow the GitHub Flow Workflow:

  1. Fork the project
  2. Check out the master branch
  3. Create a feature branch
  4. Write code and tests for your change
  5. From your branch, make a pull request against https://github.com/spotify/voyager
  6. Work with repo maintainers to get your change reviewed
  7. Wait for your change to be pulled into https://github.com/spotify/voyager/master
  8. Delete your feature branch

Testing

We use tox for testing - running tests from end-to-end should be as simple as:

pip3 install tox
tox

Style

Use clang-format for C++ code, and black with defaults for Python code.

In order to check and run formatting within the python module, you can use tox to facilitate this.

cd python
# Check formatting only (don't change files)
tox -e check-formatting
# Run formatter for python bindings and native python code
tox -e format

Issues

When creating an issue please try to ahere to the following format:

One line summary of the issue (less than 72 characters)

### Expected behaviour

As concisely as possible, describe the expected behaviour.

### Actual behaviour

As concisely as possible, describe the observed behaviour.

### Steps to reproduce the behaviour

List all relevant steps to reproduce the observed behaviour.

Pull Requests

Files should be exempt of trailing spaces.

We adhere to a specific format for commit messages. Please write your commit messages along these guidelines. Please keep the line width no greater than 80 columns (You can use fmt -n -p -w 80 to accomplish this).

One line description of your change (less than 72 characters)

Problem

Explain the context and why you're making that change.  What is the problem
you're trying to solve? In some cases there is not a problem and this can be
thought of being the motivation for your change.

Solution

Describe the modifications you've done.

Result

What will change as a result of your pull request? Note that sometimes this
section is unnecessary because it is self-explanatory based on the solution.

Some important notes regarding the summary line:

  • Describe what was done; not the result
  • Use the active voice
  • Use the present tense
  • Capitalize properly
  • Do not end in a period — this is a title/subject
  • Prefix the subject with its scope

Documentation

We also welcome improvements to the project documentation or to the existing docs. Please file an issue.

First Contributions

If you are a first time contributor to voyager, familiarize yourself with the:

When you're ready, navigate to issues. Some issues have been identified by community members as good first issues.

There is a lot to learn when making your first contribution. As you gain experience, you will be able to make contributions faster. You can submit an issue using the question label if you encounter challenges.

License

By contributing your code, you agree to license your contribution under the terms of the LICENSE.

Code of Conduct

Read our Code of Conduct for the project.

Troubleshooting

Building the project

ModuleNotFoundError: No module named 'pybind11'

Try updating your version of pip:

pip install --upgrade pip

Failed to establish a new connection: [Errno -2] Name or service not known'

You may have networking issues. Check to make sure you do not have the PIP_INDEX_URL environment variable set (or that it points to a valid index).

fatal error: Python.h: No such file or directory

Ensure you have the Python development packages installed. You will need to find correct package for your operating system. (i.e.: python-dev, python-devel, etc.)

AttributeError: 'NoneType' object has no attribute 'group'

  • Ensure that you have Tox version 4 or greater installed
  • or set ignore_basepython_conflict=true in tox.ini
  • or install Tox using pip and not your system package manager