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 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.

$ 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 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!