From 0eb0e23a52e3fbcee1ab5a0bb4f6ab4685bd3a69 Mon Sep 17 00:00:00 2001
From: Mike Gouline <1960272+gouline@users.noreply.github.com>
Date: Wed, 14 Feb 2024 19:55:44 +1100
Subject: [PATCH] Contribution guidelines

---
 CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 12 +++-----
 2 files changed, 79 insertions(+), 8 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..d690ec3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing Guidelines
+
+This project would not be here without its community, so contributions have and will always be welcome!
+
+## Questions
+
+If you have a **question** or an **idea**, please ensure it has not been raised by using search first and then create a [discussion](https://github.com/gouline/dbt-metabase/discussions) under the appropriate category. This makes accepted answers and conversations available for others in the same situation.
+
+## Issues
+
+When reporting a bug, please create an [issue](https://github.com/gouline/issues) and provide as much content as humanly possible:
+
+* Package version (`dbt-metabase --version` or `pip show dbt-metabase`)
+* Environment details, e.g. operating system, cloud provider, database
+* Steps to reproduce
+* Expected vs actual results
+* Sample code, logs, screenshots
+
+## Pull Requests
+
+Code contributions must be reviewed by the maintainer, please create a [pull request][https://github.com/gouline/pulls] and wait patiently. This project only has one maintainer, so this may take days or weeks.
+
+Unless your change is a bug fix or an incremental addition, consider creating a discussion or an issue to propose your approach first. While your contributions are welcome, not everything is suitable for this project and discussing your idea ahead of time avoids wasting your time implementing something that ultimately gets rejected.
+
+### Validation
+
+While checks and tests are run automatically on pull requests, GitHub Actions requires maintainers to manually approve new contributors. This means you could spend days waiting for a code review only to be immediately rejected because checks and/or tests failed. To avoid this, please **run checks locally before you commit**!
+
+To execute only checks (you can also run each check separately, e.g. `check-fmt`):
+
+```
+make check
+```
+
+To execute only tests:
+
+```
+make test
+```
+
+The most convenient way to fix formatting and imports, and run checks and tests, with one command:
+
+```
+make pre
+```
+
+### Tests
+
+Any code you contribute **must have unit tests**. Bug fixes in particular require at least one test case that fails before your fix and succeeds afterwards. This helps communicate how your contribution works and ensures no future changes inadvertently break it.
+
+### Sandbox
+
+While developing, it can be useful to have a sandbox with Metabase, dbt and PostgreSQL running locally to execute your changes against. To start Docker Compose containers, run the following (see [.env](./sandbox/.env) for ports and credentials):
+
+```
+make sandbox-up
+```
+
+To execute dbt-metabase commands against it:
+
+```
+make sandbox-models
+make sandbox-exposures
+```
+
+Once you are finished, stop the sandbox:
+
+```
+make sandbox-down
+```
+
+## Code of Conduct
+
+All contributors are expected to follow the [PSF Code of Conduct](https://www.python.org/psf/conduct/).
+
diff --git a/README.md b/README.md
index 67412db..673aa3c 100644
--- a/README.md
+++ b/README.md
@@ -18,13 +18,13 @@ Requires Python 3.8 or above.
 
 You can install dbt-metabase from [PyPI](https://pypi.org/project/dbt-metabase/):
 
-```shell
+```
 pip install dbt-metabase
 ```
 
 Sections below demonstrate basic usage examples, for all CLI options:
 
-```shell
+```
 dbt-metabase --help
 ```
 
@@ -77,7 +77,7 @@ models:
 
 This is already enough to propagate the primary keys, foreign keys and descriptions to Metabase:
 
-```shell
+```
 dbt-metabase models \
     --manifest-path target/manifest.json \
     --metabase-url https://metabase.example.com \
@@ -204,7 +204,7 @@ If you have known discrepancies between dbt and Metabase and wish to proceed wit
 
 dbt-metabase allows you to extract questions and dashboards from Metabase as [dbt exposures](https://docs.getdbt.com/docs/building-a-dbt-project/exposures) in your project:
 
-```shell
+```
 dbt-metabase exposures \
     --manifest-path ./target/manifest.json \
     --metabase-url https://metabase.example.com \
@@ -300,7 +300,3 @@ c.extract_exposures(
 ```
 
 See function header comments for information about other parameters.
-
-## Code of Conduct
-
-All contributors are expected to follow the [PSF Code of Conduct](https://www.python.org/psf/conduct/).