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)
ordefault=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!