diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 316594b7..327d6305 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,17 +58,20 @@ This will create a base migration for the new version and will create incrementa All changes to SQL should only be made in the `/src/pgstac/sql` directory. SQL Files will be run in alphabetical order. ### Adding Tests + +There are three different types of tests within the project: (1) pgTap tests, (2) basic SQL tests, and (3) PyPgSTAC tests. + PgSTAC tests can be written using PGTap or basic SQL output comparisons. Additional testing is available using PyTest in the PyPgSTAC module. Tests can be run using the `scripts/test` command. -PGTap tests can be written using [PGTap](https://pgtap.org/) syntax. Tests should be added to the `/src/pgstac/tests/pgtap` directory. Any new sql files added to this directory must be added to `/src/pgstac/tests/pgtap.sql`. +PGTap tests can be written using [PGTap](https://pgtap.org/) syntax. Tests should be added to the `/src/pgstac/tests/pgtap` directory. Any new SQL files added to this directory must be added to `/src/pgstac/tests/pgtap.sql`. The Basic SQL tests will run any file ending in '.sql' in the `/src/pgstac/tests/basic` directory and will compare the exact results to the corresponding '.sql.out' file. -PyPgSTAC tests are located in `/src/pypgstac/tests`. +PyPgSTAC tests are pytest tests, and they are located in `/src/pypgstac/tests` -All tests can be found in tests/pgtap.sql and are run using `scripts/test` +All tests can be found in tests/pgtap.sql and are run using `scripts/test`. -Individual tests can be run with any combination of the following flags "--formatting --basicsql --pgtap --migrations --pypgstac". If pre-commit is installed, tests will be run on commit based on which files have changed. +Individual tests can be run with any combination of the following flags `--formatting --basicsql --pgtap --migrations --pypgstac`. If pre-commit is installed, tests will be run on commit based on which files have changed. ### To make a PR @@ -96,3 +99,13 @@ Individual tests can be run with any combination of the following flags "--forma ### Get Involved Issues and pull requests are more than welcome: https://github.com/stac-utils/pgstac/issues + +### A Note on Hydration and Dehydration + +Dehydration refers to stripping redundant attributes of STAC items when storing them within the database. For many collections, dehydration saves a significant amount of memory. + +Rehydration is the process of adding the stripped attributes back to the STAC items, such as during the export of an STAC collection or the response to a search query. + +PgSTAC, a versatile tool, is designed to seamlessly integrate with PyPgSTAC or alternative backends. This flexibility allows for direct calls for both rehydration and dehydration, giving developers and technical users a sense of control over the process. + +Hydration and dehydration are de-facto settings that users can not opt out of. In the future, we may provide a configuration for use cases where the size benefits do not justify the added complexity. \ No newline at end of file