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.