Add a CONTRIBUTING.md file

Author: nineinchnick

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+Contributing to usql
+====================
+
+Any contributions are welcome. If you found a bug, or a missing feature,
+take a look at existing [issues](https://github.com/xo/usql/issues)
+and create a new one if needed.
+
+You can also open up a [pull request](https://github.com/xo/usql/pulls) (PR)
+with code or documentation changes.
+
+# Adding a new driver
+
+1. Add a new schema in [dburl](https://github.com/xo/dburl).
+1. Create a new go package in `drivers`. It should have an `init()` function, that would call `drivers.Register()`.
+1. Regenerate code in the `internal` package by running `internal/gen.sh`.
+1. Add any new required modules using `go get` or by editing `go.mod` manually and running `go mod tidy`.
+1. Run all tests, build `usql` and see if the new driver works.
+1. Update `README.md`.
+
+> Tip: check out closed PRs for examples, and/or search the codebase
+for names of databases you're familiar with.
+
+# Enabling metadata introspection for a driver
+
+For `\d*` commands to work, `usql` needs to know how to read the structure of a database.
+A driver must provide a metadata reader, by setting the `NewMetadataReader` property
+in the `drivers.Driver` structure passed to `drivers.Register()`. This needs to be a function
+that given a database and reader options, returns a reader instance for this particular driver.
+
+If the database has a `information_schema` schema, with standard tables like `tables` and `columns`,
+you can use an existing reader from the `drivers/informationschema` package.
+Since there are usually minor difference in objects defined in that schema in different databases,
+there's a set of options to configure this reader. Refer to
+the [package docs](https://pkg.go.dev/github.com/xo/usql/drivers/metadata/informationschema) for details.
+
+If you can't use the `informationschema` reader, consider implementing a new one.
+It should implement at least one of the following reader interfaces:
+* CatalogReader
+* SchemaReader
+* TableReader
+* ColumnReader
+* IndexReader
+* IndexColumnReader
+* FunctionReader
+* FunctionColumnReader
+* SequenceReader
+
+Every of these interfaces consist of a single function, that takes a `Filter` structure as an argument,
+and returns a set of results and an error.
+
+Example drivers using their own readers include:
+* `sqlite3`
+* `oracle` and `godror` sharing the same reader
+
+If you want to use the `informationschema` reader, but need to override one or more readers,
+use the `metadata.NewPluginReader(readers ...Reader)` function. It returns an object calling
+reader functions from the last reader passed in the arguments, that implements it.
+
+Example drivers extending an `informationschema` reader using a plugin reader:
+* `postgres`
+
+`\d*` commands are actually implemented by a metadata writer. There's currently only one,
+but it too can be replaced and/or extended.
+
+# Enabling autocomplete for a driver
+
+If a driver provides a metadata reader, the default completer will use it.
+A driver can provide it's own completer, by setting the `NewCompleter` property
+in the `drivers.Driver` structure passed to `drivers.Register()`.