docs: update project documentation - #2786
Conversation
annabkr
left a comment
annabkr
left a comment
There was a problem hiding this comment.
Thank you so much for picking this up! I'll be curious to get more feedback from the rest of the team.
| # Contributing to Auth | ||
|
|
||
| We would love to have contributions from each and every one of you in the community be it big or small and you are the ones who motivate us to do better than what we do today. | ||
| Thanks for your interest in improving Auth. Contributions of every size are welcome. Follow our [Code of Conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md). |
There was a problem hiding this comment.
personally, I prefer the previous intro because it feels a bit more warm.
There was a problem hiding this comment.
I'll revert this change.
| Auth sits at the center of Supabase, and coordinating up front lets the team weigh in on the approach and line the work up with the rest of the project before effort is spent. | ||
|
|
||
| ## Quick Start | ||
| Auth ships to a large and growing number of self-hosted and managed deployments. You cannot predict how any given project's database is configured or what has been customized, so schema changes and other risky changes carry outsized impact. Coordinate them early. |
There was a problem hiding this comment.
Coordinate them early.
I'm not fully clear on what this means to a contributor
There was a problem hiding this comment.
I was wondering if it would be helpful to contributors to understand the varying concerns that we juggle with internally before accepting a patch. Perhaps, this is unnecessary asking for empathy where empathy isn't necessary or relevant. I'm not fully sold on this myself so I'm happy to remove it.
| ## Before you start | ||
|
|
||
| Please help us keep all our projects open and inclusive. Kindly follow our [Code of Conduct](CODE_OF_CONDUCT.md) to keep the ecosystem healthy and friendly for all. | ||
| For anything beyond a trivial fix, open a [Discussion](https://github.com/supabase/supabase/discussions) before you start writing code. |
There was a problem hiding this comment.
Should the process be discussion -> issue -> maintainer triage (ala the CLI repo) -> pull-request?
I'd like it if we could set up automation to automatically close PRs that to not link to an issue, for example.
There was a problem hiding this comment.
Steps:
- Discussion: State the problem and discuss it to make sure we have a shared understanding and route it to the appropriate team.
- Issue: Break down the problem into an actionable chunk of work.
- PR: Build the solution.
This would ensure that we have a clear understanding of the problem and that we're solving it in the right place before we start to build a solution.
Is this what you're thinking?
| Auth ships to a large and growing number of self-hosted and managed deployments. You cannot predict how any given project's database is configured or what has been customized, so schema changes and other risky changes carry outsized impact. Coordinate them early. | ||
|
|
||
| Auth has a development container setup that makes it easy to get started contributing. This setup only requires that [Docker](https://www.docker.com/get-started) is setup on your system. The development container setup includes a PostgreSQL container with migrations already applied and a container running GoTrue that will perform a hot reload when changes to the source code are detected. | ||
| Meaningful pull requests opened without a prior, agreed-upon Discussion may be closed or left stale until the work has been coordinated. This is not about turning contributors away, it is about making sure your time is well spent. |
There was a problem hiding this comment.
Prefer will be closed over may. I think the guidelines we're establishing are reasonable and should be enforced, and we should add automation to enforce them, like many other much-loved OS repos do.
| - Fork the repo and create your branch from `master`. | ||
| - Keep it small: one logical change per pull request. | ||
| - Add tests with your change. CI must be green. | ||
| - Reference the accepted Discussion or issue in the pull request description. |
There was a problem hiding this comment.
As a follow-up task, we should change our PR template, too.
|
suggest also re-titling this PR to indicate it is specifically contributor docs |
2 participants
What kind of change does this PR introduce?
Docs. This change updates some of the contributor docs to provide better clarity as to which types of contributions can be accepted and why.
What is the current behavior?
The current documentation is a bit stale, verbose and outdated. It also contain another organizations Code of Conduct.
What is the new behavior?
Hopefully, the concise documents provide a little more clarity around expectations for how, what, when and why you should contribute. I also linked to the Supabase CoC.
Additional context