Skip to content

Information for developers

Jump to bottom
John Kerl edited this page Feb 15, 2023 · 10 revisions

Starter info

Spec

Docs

PRs

  • OK to branch from https://github.com/single-cell-data/TileDB-SOMA -- no need to fork-and-branch (although you can if you like)
  • Follow the PR template
  • Pro-tip: alias pav='python -m pre_commit run -a -v' before submitting the PR, to catch CI issues before they reach GitHub

Branches and releases

  • Branches: main-old, main

    • As of September 2022 the main-old branch is released at PyPI and is recommended for installation
    • The main branch is effectively a dev branch

  • PyPI: https://test.pypi.org/project/tiledbsoma/

  • Be sure to bump the tiledbsoma version at apis/r/DESCRIPTION

  • Tag at https://github.com/single-cell-data/TileDB-SOMA/releases

    • Tag off main-old for old-api-impl; when we start doing releases for new-api-impl we'll tag off main
      • If you've created a GitHub branch (not tag, branch) like 0.1.20, do not tag that branch -- instead, merge that PR back to main-old and then make the tag on main-old -- else PyPI-publish CI won't run
    • Include in the release notes all the PRs from the autogenerated changelog but organize them as follows:
      • New features added
      • Breaking changes
      • Minor changes
      • Bug fixes
      • Upcoming deprecation notices

  • In case of backport fixes we will imitate what core does wherein it uses release branches like release-2.11

  • Tagging plan:

    • While main-old is the deliverable and main is in development:
      • Release main-old as 0.1.14 etc
        • Users who want to install the existing tiledbsoma code will be able to do pip install tiledbsoma
      • Release main as 0.5.0a1 etc -- the key is the a
        • PyPI will automagically treat this as a "pre-release" at the PyPI level
        • Do not flag the GitHub release as "pre-release" at the GitHub level, so a PyPI wheel will get build
        • Do not flag as latest release at the GitHub release level
        • https://pypi.org/project/tiledbsoma/#history
        • IMPORTANT: there are (as of 0.5.0a2) manual steps you must perform to complete the release: see this how-to guide
        • Users who want to install this version can do pip install --pre tiledbsoma
    • Once main is released:
      • Continue to release main-old as 0.1.19 etc
      • Release main as 0.5.2 etc -- no a -- or, maybe 1.0.0 etc
      • Users who run pip install tiledbsoma will get this main version
      • Users who want main-old can ask for it via pip install tiledbsoma~=0.1.x

Top-level namespacing

  • Items in the top-level namespace should include things we expect a user to instantiate themselves or call directly
  • Exception: helper packages such as tiledbsoma.io
  • Anything storage-dependent should include the storage engine as a prefix or submodule: e.g. soma.tiledb_foo()
    • For Python: prefix or submodule
    • For R: use a prefix since there are no submodules in R

Automated QA

  • These run in CI, so you can run them locally (in apis/python) before putting up a PR: black, isort, flake8, mypy, python -m pytest tests
  • See also #193 for an opt-in way to use pre-commit hooks, if you prefer

Coding and code review

  • 1 reviewer suffices unless stated otherwise, unless explicitly:
    • If the author wants more than one approval, they should @-tag the people they need
    • If the one accepting reviewer says "LGTM, but I lack enough context on ____ to be sure" they should say so (and, ideally and if possible, @-tag someone who they think would be a good second approver)
  • Squash-and-merge is preferred

Using TileDB-SOMA

Developing TileDB-SOMA

Clone this wiki locally