diff --git a/README.rst b/README.rst index 785188c..4c78f76 100644 --- a/README.rst +++ b/README.rst @@ -132,12 +132,11 @@ switches, environment variables or through the ``.env`` file: +-------------------------+------------------------+-----------------+-------------------------------------------------------------------+ | ``--config`` | ``QE_CONFIG`` | ``config.yaml`` | Configuration files. Multiple values can be provided. | +-------------------------+------------------------+-----------------+-------------------------------------------------------------------+ - | | ``QE_DOTENV`` | ``$PWD/.env`` | Path for the dotenv file where environment variables can be | + | | ``QE_DOTENV`` | ``$PWD/.env`` | Path for the dotenv file where environment variables can be | | | | | provided. | +-------------------------+------------------------+-----------------+-------------------------------------------------------------------+ - Metrics endpoint ---------------- @@ -184,7 +183,7 @@ See `supported databases`_ for details. Run in Docker -------------- +============= ``query-exporter`` can be run inside Docker_ containers, and is available from the `Docker Hub`_:: @@ -218,7 +217,7 @@ Automated builds from the ``main`` branch are available on the `GitHub container ODBC driver version -~~~~~~~~~~~~~~~~~~~ +------------------- A different ODBC driver version to use can be specified during image building, by passing ``--build-arg ODBC_bVERSION_NUMBER``, e.g.:: @@ -227,7 +226,7 @@ by passing ``--build-arg ODBC_bVERSION_NUMBER``, e.g.:: Install from Snap ------------------ +================= |Get it from the Snap Store| @@ -257,6 +256,13 @@ The snap has support for connecting the following databases: s390x) +Contributing +============ + +The project welcomes contributions of any form. Please refer to the +`contribution guide`_ for details on how to contribute. + + .. _Prometheus: https://prometheus.io/ .. _SQLAlchemy: https://www.sqlalchemy.org/ .. _`supported databases`: @@ -265,6 +271,7 @@ The snap has support for connecting the following databases: .. _Docker: http://docker.com/ .. _`Docker Hub`: https://hub.docker.com/r/adonato/query-exporter .. _`configuration file format`: docs/configuration.rst +.. _`contribution guide`: docs/contributing.rst .. _`Helm chart`: https://github.com/makezbs/helm-charts/tree/main/charts/query-exporter .. _`GitHub container registry`: https://github.com/albertodonato/query-exporter/pkgs/container/query-exporter diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..28d1870 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,78 @@ +Thanks for considering contributing to query-exporter! + +Issues +====== + +When submitting an issue, please include a detailed description of the issue, +what is happening, and in which conditions. + +If possible, attach a log of the exporter with debug enabled (``--log-level +debug``), as well as the (sanitized as needed) content of the configuration +file. + +Always include the exporter version (``query-exporter --version``), as well as +the installation method. + + +Enhancements +============ + +When proposing enhancements, please describe in detail the use cases or +problems that the enhancement would solve. + +If possible, include examples of the new behavior with the change. + + +Pull requests +============= + +Creating pull requests is very easy, and requires just a minimal development +setup is requested to verify the changes. + +When creating a pull request for a non-trivial bug or enhancement, please +consider creating an issue first, so that discussion can happen more easily, +and reference it in the pull request. + +Prerequisites +------------- + +The development environment requires having ``tox`` installed. Please refer to +to the `Tox wiki`_ for installation instructions. + +Please make sure that you run the following steps on your changes before +creating the pull request. + +Tests +----- + +Changes must have full test coverage. The full suite can be run via:: + + tox run -e coverage + +which will include the coverage report. + +To just run the tests, possibly limiting to a subset of them, run:: + + tox run -e py -- + +Type checking +------------- + +The project uses ``mypy`` for type checking. Please make sure types are added correctly to new/changed code. +To verify, run:: + + tox run -e check + +Linting and formatting +---------------------- + +Formatting can be applied automatically with:: + + tox run -e format + +Linting is checked on pull requests, and can be verified with:: + + tox run -e lint + + +.. _`Tox wiki`: https://tox.wiki/en/latest/index.html