Hi! Thanks for your interest in TileDB. The following notes are intended to help you file issues, bug reports, or contribute code to the open source TileDB project.
-
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 TileDB, format code, and issue pull requests (PR)'s.
A useful bug report filed as a GitHub issue provides information about how to reproduce the error.
-
Before opening a new GitHub issue try searching the existing issues to see if someone else has already noticed the same problem.
-
When filing a bug report, provide where possible:
- The version TileDB (
tiledb_version()
) or if adev
version, specific commit that triggers the error. - The full error message, including the backtrace (if possible). Verbose error reporting is enabled by building TileDB with
../bootstrap --enable-verbose
. - 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 C / C++ source file. If the code to reproduce is somewhat long, consider putting it in a gist.
- 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.
By contributing code to TileDB, you are agreeing to release it under the MIT License.
Please see building from source for dependencies and detailed build instructions.
git clone https://github.com/username/TileDB
cd TileDB && mkdir build && cd build
../bootstrap
make && make check
cd ../
git checkout -b <my_initials>/<my_bugfix_branch>
... code changes ...
make -C build format
make -C build check
git commit -a -m "my commit message"
git push --set-upstream origin <my_initials>/<my_bugfix_branch>
Issue a PR from your updated TileDB fork
Branch conventions:
dev
is the development branch of TileDB, all PR's are merged intodev
.master
tracks the latest stable / released version of TileDB.release-x.y.z
are major / bugfix release branches of TileDB.
Formatting conventions:
- 2 spaces per indentation level not tabs
- class names use CamelCase
- member functions, variables use lowercase with underscores
- class member variables use a trailing underscore
foo_
- comments are good, TileDB uses doxygen for class doc strings.
- format code using clang-format
TileDB can be built with clang sanitizers enabled. To enable them, you have to bootstrap with the --enable-sanitizer
flag, as well as the vcpkg base triplet corresponding to your platform. The following platforms support sanitizers:
arm64-osx
x64-linux
x64-osx
x64-windows
Note
Currently only the address
sanitizer is supported.
cd TileDB && mkdir build-asan && cd build-asan
../bootstrap --enable-sanitizer=address --vcpkg-base-triplet=x64-linux
make && make check
Important
To avoid errors, building with sanitizers must be done in a separate build directory.
-
dev
is the development branch, all PR’s should be rebased on top of the latestdev
commit. -
Commit changes to a local branch. The convention is to use your initials to identify branches: (ex. “Fred Jones” ,
fj/my_bugfix_branch
). Branch names should be identifiable and reflect the feature or bug that they want to address / fix. This helps in deleting old branches later. -
Make sure the test suite passes by running
make check
. -
When ready to submit a PR,
git rebase
the branch on top of the latestdev
commit. Be sure to squash / cleanup the commit history so that the PR preferably one, or a couple commits at most. Each atomic commit in a PR should be able to pass the test suite. -
Run the limiting / code format tooling (
make format
) before submitting a final PR. Make sure that your contribution generally follows the format and naming conventions used by surrounding code. -
If the PR changes/adds/removes user-facing API or system behavior (such as API changes), add a note to the
TileDB/HISTORY.md
file. -
Submit a PR, writing a descriptive message. If a PR closes an open issue, reference the issue in the PR message (ex. If an issue closes issue number 10, you would write
closes #10
) -
Make sure CI (continuous integration) is passing for your PR -- click
Show all checks
in the pull request status box at the bottom of each PR page. The continuous integration project pages will also list all recently-built PRs:
- TileDB uses Sphinx as its documentation generator.
- Documentation is written in reStructuredText markup.
Building the docs locally:
$ cd TileDB/doc
$ ./local-build.sh
This will install all the required packages in a Python virtual environment, and build the docs locally. You can then open the doc/source/_build/html/index.html
file in your browser.
Note: If there are additions to the C/C++ API in between builds, rerun bootstrap:
$ cd ../build
$ ../bootstrap <flags>