Contributing to TileDB-CF-Py

Thank you for your interest in contributing to TileDB-CF-Py. The following notes are intended to help you file issues, bug reports, or contribute code to this open source project.

Contributing Checklist

  • Reporting a bug? Please read how to file a bug report section to make sure sufficient information is included.

  • Contributing code? You rock! Be sure to review the contributor section for helpful tips on the tools we use to build this project, format code, and issue pull requests (PR)’s.

Note: All participants in TileDB spaces are expected to adhere to a high standard of profectionalism in all interactions. See the code of conduct for more information.

Reporting a Bug

A useful bug report filed as a GitHub issue provides information about how to reproduce the error.

  1. Before opening a new GitHub issue try searching the existing issues to see if someone else has already noticed the same problem.

  2. When filing a bug report, provide where possible:

    • The version of TileDB-CF-Py or if a dev version, the specific commit that triggers the error.
    • The full error message, including the backtrace (if possible).
    • A minimal working example, i.e. the smallest chunk of code that triggers the error. Ideally, this should be code that can be a small reduced python file. If the code to reproduce is somewhat long, consider putting it in a gist.

  3. When pasting code blocks or output, put triple backquotes (```) around the text so GitHub will format it nicely. Code statements should be surrounded by single backquotes (`). See GitHub’s guide on Markdown for more formatting tricks.

Contributing Code

By contributing code to TileDB-CF-Py, you are agreeing to release it under the MIT License.

Quickstart Workflow

From a fork of TileDB-CF-Py

git clone https://github.com/username/TileDB-CF-Py
pip install -e '.[parallel]'
git checkout -b <my_initials>/<my_bugfix/feature_branch>
# ... code changes ...
./tools/lint.sh # run linters
git commit -a -m "descriptive commit message"
git push --set-upstream origin <my_initials>/<my_bugfix_branch>

Issue a PR from your updated TileDB-CF-Py fork

Branch conventions:

  • dev is the development branch of TileDB-CF-Py, all PR’s are merged into dev.
  • release-x.y.z are major / bugfix release branches.

Building Locally for Development

This project uses setuptools for its build system, and can be built locally using pip. It is recommended you set-up a Python virtual environment with your preferred method before installing. Once the virtual environment is activated, install tiledb.cf as ‘editable’ using pip:

pip install -e .

The following tools are used for testing, linting, and formatting. You may want to install them either in the local virtual environment or as command line tools for you system:

  • black
  • flake8
  • mypy
  • pytest (with pytest-cov)

Formatting, Style, and Linting

  • 4 spaces per indentation level not tabs
  • class names use CamelCase
  • member functions, variables use snake_case
  • private module or class member use a leading underscore _local_variable
  • comments are good, the project uses Google-style docstrings with type hints
  • format code using black and isort
  • lint code using flake8 and mypy

It is highly recommended to run formatting and linting tools before every commit. This can be automated by activating the pre-commit hook tools/hooks/pre-commit.sh. To do this symlink or copy tools/hooks/pre-commit.sh to .git/hooks/pre-commit in the local directory. Note that the pre-commit hook may fail due to unstaged changes. You may wish to stash these changes before committing. This can be done as follows:

git add <files-to-be-added>
git stash --keep-index
git commit
git stash pop

Testing

The testing for this project uses pytest and GitHub workflows for testing. The test suite will be run on GitHub when you submit your pull request.

API Documentation

To build the API documentation do the following from this projects root directory:

  1. Install required packages:

    python3 -m pip install tiledb-cf[docs]

  2. Make the HTML document:

    make -C docs/ html

  3. Open docs/_build/html/index.html in a web browser of your choice.

Pull Requests

  • dev is the development branch, all PR’s should be rebased on top of the latest dev commit.

  • Commit changes to a local branch. The convention is to use your initials to identify branches. Branch names should be identifiable and reflect the feature or bug that they want to address / fix. This helps in deleting old branches later.

  • When ready to submit a PR, git rebase the branch on top of the latest dev commit. Be sure to squash / cleanup the commit history so that the PR preferably one, or a couple commits at most. All commits will be squashed into a single commit upon merging.

  • Run the formatting (isort, black) and linting tools (flake8, mypy) before submitting a final PR. Make sure that your contribution generally follows the format and naming conventions used by surrounding code.

  • Update the HISTORY with any changes/adds/removes to user-facing API or system behavior. Make sure to note any non-backward compatible changes as a breaking change.

  • Submit a PR, writing a descriptive message. If a PR closes an open issue, reference the issue in the PR message (e.g. If an issue closes issue number 10, you would write closes #10)

  • Make sure CI (continuous integration) is passing for your PR.

Resources