Skip to content

Contribution Guidelines

Thank you for considering contributing to Giga! We value your input and aim to make the contribution process as accessible and transparent as possible. Whether you're interested in reporting bugs, discussing code, submitting fixes, proposing features, becoming a maintainer, or engaging with the Giga community, we welcome your involvement.

Adding a dataset

A dataset published as files is a handler. A dataset served as a query is a fetcher. The handler base, including the search key and the search geometry, is documented in the API reference: Handler base. That section is for contributors to this repository. It is not a stable API for other packages.

Where a new dataset goes:

  • A handler goes in gigaspatial/handlers/. Add its config, downloader, reader, and handler to the dictionary in gigaspatial/handlers/__init__.py, and the handler alone to the one in gigaspatial/__init__.py.
  • A fetcher goes in gigaspatial/fetchers/ and its class name ends in Fetcher. Register it in gigaspatial/fetchers/__init__.py and gigaspatial/__init__.py.
  • An image downloader goes in gigaspatial/image_downloaders/. Add it to that package's __all__ and to gigaspatial/__init__.py.

Those __init__.py files load names lazily. Each one also repeats its names in an if TYPE_CHECKING: block, and tests/test_public_api.py fails if the two lists differ. Code inside the package uses absolute imports (from gigaspatial.handlers.ghsl import ...). The reasons are in Public import paths.

With a coding agent

Team members can install agent skills for this repository from the team's skills repository, a submodule at .agents/vendor/di-applied-science-skills. From the repository root:

git submodule update --init
python .agents/vendor/di-applied-science-skills/install.py giga-spatial

The skills land in .agents/skills/, which Cursor and Codex read and git ignores. Invoke them by name:

  • build-handler probes a dataset's source, interviews you on the design, and writes the handler, its registrations, and its tests.
  • judge-handler-base reviews a new handler, or a change to the handler base, against the contract in .agents/reference/handler-contract.md.

The contract lives here because it describes this repository's code; update it with any change to the handler base. The skills themselves are edited in the skills repository. After the submodule moves to a newer commit, run install.py again with no arguments.

Tests marked live reach real data sources and are skipped by default. Run them with pytest -m live.

How to Contribute to our Giga Project?

  1. Familiarize Yourself: Before contributing, familiarize yourself with the project by reviewing the README, code of conduct, and existing issues or pull requests.
  2. Issues and Feature Requests: Check the issue tracker for existing issues or create a new one to report bugs, suggest improvements, or propose new features.
  3. Fork and Branch: Fork the repository and create a branch for your contribution. Branch names should be descriptive (e.g., feature/add-new-functionality, bugfix/issue-description).
  4. Code Changes: Make changes or additions following our coding conventions and style guide. Ensure to write clear commit messages that explain the purpose of each commit.
  5. Testing: If applicable, include tests for the changes made to ensure code reliability. Ensure existing tests pass.
  6. Documentation: Update relevant documentation, including README files or any other necessary guides.
  7. Pull Request: Open a pull request (PR) against the main branch. Clearly describe the changes introduced, referencing any related issues.

Report a Bug or Suggestion

  • Bug Reports: Help us understand and address issues by submitting detailed bug reports via GitHub issues. Include as many relevant details as possible in the provided template to expedite resolutions.
  • Suggestions: Share your ideas, feedback, or stay updated on Giga by joining our Discord channel.

Making Changes and Pull Requests

To contribute code changes:

  1. Fork the repository and create a new branch for your contribution

    git checkout -b 'my-contribution'.

  2. Make your changes on the created branch.
  3. Commit with clear messages describing the updates.
  4. Submit a pull request in the main repository, ensuring the following:
  5. Clear use case or demonstration of bug fix/new feature.
  6. Inclusion of relevant tests (unit, functional, and fuzz tests where applicable).
  7. Adherence to code style guidelines.
  8. No breaking changes to the existing test suite.
  9. Bug fixes accompanied by tests to prevent regression.
  10. Update of relevant comments and documentation reflecting code behavior changes.

Contributing with an Issue

If you encounter a bug but aren't sure how to fix it or submit a pull request, you can create an issue. Issues serve as avenues for bug reports, feedback, and general discussions within the GigaSpatial GitHub repository.

Other Ways to Contribute

Beyond code contributions:

  • Feedback and Insights: Share your expertise and experiences related to cash transfer by contacting us at giga@unicef.org.
  • Documentation: Contribute to our journey by sharing reports, case studies, articles, blogs, or surveys. Contact us to contribute and learn more via giga@unicef.org.
  • Designs: If you're passionate about UI/UX, animations, graphics, tutorials, etc., contact us to create visuals for the Giga community via giga@unicef.org.

Connect with Giga Contributors

Connect with fellow contributors via our Discord channel to engage with the Giga community: Click