Summary

While the package is well-written, easy to navigate, and well-documented for package consumers, the contributing docs could be augmented with additional details, tips, and tricks for people who want to become productive contributors more quickly.

Rationale

While the package is excellent, its feature set is lagging behind some competitors like Hasura. Ideally, documentation improvements would reduce the barrier to entry for the community to get involved and can help encourage more community PRs for patches and new features. Leaning on the community more can foster engagement and buy-in in the ecosystem and lead to a faster release cycle.

Additionally, while it's clear the maintenance team is dedicated to the success of the package, it also seems that the team is spread fairly thin. Delegating more development to the community will give the maintainers the ability to set high-level vision and architectural goals while improving overall throughput.

Design

[ ] add additional platform-agnostic details on getting up and running locally, with recommendations for spinning up local databases that play well with common workflows outside of pg_graphql maintenance
[ ] add guides for creating and validating net new tests, including tips on generating output snapshots for use in tests
[ ] add a comprehensive releases and builds section
[ ] add local development workflow recommendations, especially with tips on debugging and assessing changes locally
[ ] add a link to the contributing docs in the readme

Links to external resources are fine. The idea is not to rewrite docs for how to use cargo, rust, pgrx, postgres, etc. However, starting with the assumption that maintainers may be unfamiliar with one or more tools and pointing people in the right direction regarding the most important steps could improve ramp-up times.

Examples

I have run queries locally and have manually validated the expected output, how can I quickly develop a snapshot of the outputs for use in tests?
I have made some changes to the code, but I would like to validate some assumptions. How can I debug the changes? Is print statement debugging possible?
I made a patch that got merged in. What needs to happen for me to be able to use it in supabase?

Drawbacks

Good docs take time, time which puts other features on the back-burner.
There are no guarantees that the docs will be used in any meaningful way.

Alternatives

Do nothing, expect contributors to be savvy enough to get up and running on their own. This isn't unreasonable and should be a baseline expectation.

Unresolved Questions

Are there common issues would-be contributors often encounter that prevents them from contributing?
Are there other known documentation improvements that can be added?

supabase / pg_graphql

Augment contributing docs #558