Contribution Guide
There are many ways to contribute to QtPyVCP, and all are encouraged and greatly appreciated:
contributing bug reports and feature requests
contributing documentation (and yes that includes this document)
reviewing and triaging any bugs and merge requests
testing and providing feedback on problems / bugs
Before you go any further, be reassured that your contribution, however slight, is valuable. Even if it is something as simple as fixing a spelling error, or clarifying a sentence in the docs.
Guidelines
We don’t have any strict guidlines, you are encouraged to contribute in whatever way you are capable of, and most importantly, have fun and hopefully learn something in the process. That being said, bellow are a few recommendations that should make it easier for all evolved.
Development Workflow
In general we try to use the Feature Branch and Merge requests workflow. If you are not familiar with git workflows don’t worry, it’s very straight forward (and we are not strict about it anyway).
Commit Messages
While by no means required, it is nice if you prefix commit messages
with a TLA (Three Letter Acronym) indicating the commit type. This makes
it easy to visually scan the commit log and see what types of changes
were made. It also makes it possible to grep for specific commit types.
For example, to view all BugFix commits you can use git log --grep=BUG.
Maybe most importantly, commit prefixes are used to auto-generate change
logs for each release.
TLA |
Description |
|---|---|
API |
an (incompatible) API change |
BLD |
change related to building |
BUG |
bug fix |
DEP |
deprecate something, or remove a deprecated object |
DEV |
development tool or utility |
DOC |
documentation |
ENH |
enhancement |
MNT |
maintenance commit (refactoring, typos, etc.) |
REV |
revert an earlier commit |
STY |
style fix (whitespace, PEP8) |
TST |
addition or modification of tests |
REL |
related to a release (increment version numbers etc.) |
WIP |
work in progress |
SIM |
change related to linuxcnc sim configs |
VCP |
work on example VCPs |
With that in mind, an ideal commit message might look something like this:
DOC: add example commit message to development guidelines (See #42)
The first line of a commit message should start with a capitalized acronym
(options in table above) indicating the commit type, and a short summary.
If the commit is related to a GitHub issue, then indicate that with
"Fixes #42", "See #42", "Closes #42" or similar.
If this is not enough to fully describe the commit, then add a blank line
and more text as needed. Lines shouldn't be longer than 72 characters so
they display well when viewing the git log in a terminal.
Do we live in an ideal world? No. It’s fine if your commit messages vary from this format, but you should at least try to use TLAs for commits you would like to show up on in the change logs.
Python Docstrings
It is appreciated if you document your code by writing docstrings for all python modules, classes and functions. These are automatically converted by Sphinx into HTML documentation. Docstrings should follow the Google style guidelines, example of which can be found here.