Thank you for your interest in contributing to this project!
We appreciate issue reports, pull requests for code and documentation, as well as any project-related communication through GitHub Discussions.
To get started with development, you can follow these steps (requires an installation of uv
):
-
Clone this repository:
git clone https://github.com/aai-institute/lakefs-spec.git
-
Navigate to the directory and install the development dependencies into a virtual environment:
cd lakefs-spec uv sync --all-groups
-
After making your changes, verify they adhere to our Python code style by running
pre-commit
:uv run pre-commit run --all-files
You can also set up Git hooks through
pre-commit
to perform these checks automatically:uv run pre-commit install
-
To run the tests against an ephemeral lakeFS instance, you just run
pytest
:uv run pytest
To spin up a local lakeFS instance quickly for testing, you can use the Docker Compose file bundled with this repository:
docker-compose -f hack/compose.yml up
Dependencies should stay locked for as long as possible, ideally for a whole release. If you have to update a dependency during development, you should do the following:
- If it is a core dependency needed for the package, add it to the
dependencies
section in thepyproject.toml
viauv add <dep>
. - In case of a development dependency, add it to the
dev
section of theproject.dependency-groups
table instead (uv add --group dev <dep>
). - Dependencies needed for documentation generation are found in the
docs
sections ofproject.dependency-groups
(uv add --group docs <dep>
).
After adding the dependency in either of these sections, lock all dependencies again:
uv lock
Improvements or additions to the project's documentation are highly appreciated.
The documentation is based on the MkDocs and Material for MkDocs (mkdocs-material
) projects, see their homepages for in-depth guides on their features and usage. We use the Numpy documentation style for Python docstrings.
To build the documentation locally, you need to first install the optional docs
dependencies from pyproject.toml
, e.g., with uv sync --group docs
.
You can then start a local documentation server with uv run mkdocs serve
, or build the documentation into its output folder in public/
.
In order to maintain documentation for multiple versions of this library, we use the mike tool, which automatically maintains individual documentation builds per version and publishes them to the gh-pages
branch.
The GitHub CI pipeline automatically invokes mike
as part of the release process with the correct version and updates the GitHub pages branch for the project.