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.