Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
173 lines (116 loc) · 4.58 KB

CONTRIBUTING.md

File metadata and controls

173 lines (116 loc) · 4.58 KB

Quilt is an open source project, and we welcome contributions from the community.

Contributors must adhere to the Code of Conduct.

If you are looking for a quick map of where major components live, start with the repository README.md.

Reporting issues

Unsure about something? To get support, check out our Slack community.

Found a bug? File it in our GitHub issues.

Cloning

To work on quilt you will first need to clone the repository.

git clone https://github.com/quiltdata/quilt

You can then set up your own branch version of the code, and work on your changes for a pull request from there.

cd quilt
git checkout -B new-branch-name

Local package development

Choose your area first:

  • Python SDK and CLI work: api/python
  • Web catalog work: catalog
  • AWS services and background processing: lambdas
  • Platform and user docs: docs

Python Environment

We use uv for dependency management. First, install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

uv ensures the environment is properly set up before executing a command, so you don't have to do anything else.

Run uv run poe to see all configured tasks (or refer to pyproject.toml).

Python Testing

All new code contributions are expected to have complete unit test coverage, and to pass all preexisting tests.

Use pytest to test your changes during normal development:

cd api/python
# Run all tests
uv run poe test

# Run tests verbosely
uv run poe test-verbose

# Run with coverage
uv run poe test-cov

# Run specific test file directly
uv run poe test tests/test_util.py

Local catalog development

Note that, at the current time, it is only possible to run a local catalog if you already have a catalog deployed to AWS, because the catalog relies on certain services (namely, AWS Lambda and the AWS Elasticsearch Service) which cannot be run locally.

Catalog Environment

Use npm to install the catalog dependencies locally:

cd catalog
npm install

Build

To build a static code bundle, as would be necessary in order to serve the catalog:

npm run build

To run the catalog locally, create a development config:

cp config.js.example static-dev/config.js
# edit static-dev/config.js for your environment

To run the catalog in developer mode:

npm start

This uses webpack under the hood to compile code changes on the fly and provide live reloading, useful when developing.

Make sure that any images you check into the repository are optimized at check-in time.

Catalog Testing

To run the catalog unit tests:

npm run test

Creating a release

  1. Once you are ready to cut a new release, update the version in api/python/pyproject.toml (uv version can help with this) and in docs/CHANGELOG.md.
  2. Create PR with these changes.
  3. Once PR is merged, create a tag from commit with merge: git tag $VERSION $COMMIT_HASH.
  4. Once you push the tag to GitHub with git push origin $VERSION a new CI build that makes PyPI release is triggered.

Updating documentation

Documentation is served via GitBook, and is based on the docs/ folder in the master branch of the quilt repository.

Documentation changes go live at pull request merge time. There is currently no way to preview documentation updates except locally.

Updating the API Reference

The API Reference section of the documentation is served by processing the docstrings in the codebase using a script. We use our own fork of the pydoc-markdown package to do the necessary work.

To modify the API Reference, modify the docstring associated with a method of interest.

Then, run uv run poe gendocs from the api/python directory.

The resulting files will land in docs/ and will be ready to be checked in.

Updating everything else

All other pages in the documentation are served from corresponding Markdown pages in the docs directory. To edit the page, edit the Markdown file. Then check that file in.

License

Quilt is open source under the Apache License, Version 2.0.