==========================
Contributing to grafanalib
==========================

Thank you for contributing to grafanalib!
Here are some notes to help you get your PR merged as quickly as possible,
and to help us remember how to review things properly.

If something comes up during a code review or on a ticket that you think should be part of these guidelines, please say so, or even file a PR to make this doc better!

Code of conduct
===============

We have a :doc:`code of conduct <../CODE_OF_CONDUCT>`, and we enforce it. Please take a look!

Coding guidelines
=================

* Python 3 all the way
* Must be `flake8`_ compliant
* We use `attrs`_ everywhere
* Avoid inheritance as much as possible
* Avoid mutation as much as possible—keep things purely functional
* Docstrings are great, let's have more of those
* Link to official Grafana docs in comments as much as possible

Conventions
-----------

* Classes are ``StudlyCaps``
* Attributes are ``camelCased``
* Methods are ``snake_cased``
* Local variables are ``snake_cased``
* We're kind of fussy about indentation:
  4 spaces everywhere, follow the examples in `core.py`_ if you're uncertain
* Triple Double quotes `"""` for docstrings
* Double quotes "" for human readable message or when string used for interpolation
* Single quotes '' for symbol like strings

Testing
-------

Lots of grafanalib is just simple data structures, so we aren't fastidious about test coverage.

However, tests are strongly encouraged for anything with non-trivial logic.
Please try to use `hypothesis`_ for your tests.

.. code-block:: console

  $ make all

Gotchas
-------

* Do **not** use mutable values as default values for attributes.
  Mutable values include lists (e.g. ``default=[RED, GREEN]``) and other grafanalib objects (e.g. ``default=Annotations()``).
  Instead, use `attr.Factory`_.
  e.g. ``default=attr.Factory(Annotations)`` or ``default=attr.Factory(lambda: [RED, GREEN])``.

Submitting a PR
===============

* We are very grateful for all PRs, and deeply appreciate the work and effort involved!
* We try to review PRs as quickly as possible, but it might take a couple of weeks to get around to reviewing your PR—sorry, we know that sucks
* Please add an entry to the :doc:`CHANGELOG <../CHANGELOG>` in your PR
* It helps a lot if the PR description provides some context on what you are trying to do and why you think it's a good idea
* The smaller the PR, the more quickly we'll be able to review it

Filing a bug
============

* Please say what you saw, what you expected to see, and how someone else can reproduce the bug
* If it comes with a test case, even better!


.. _`flake8`: http://flake8.pycqa.org/en/latest/
.. _`attrs`: http://www.attrs.org/en/stable/
.. _`CHANGELOG`: ../CHANGELOG.rst
.. _`attr.Factory`: http://www.attrs.org/en/stable/api.html#attr.Factory
.. _`hypothesis`: http://hypothesis.works/
.. _`core.py`: https://github.com/weaveworks/grafanalib/blob/main/grafanalib/core.py