Skip to content

Style Guide

Jump to bottom
Wendi Yu edited this page Jun 1, 2020 · 2 revisions

Style guide

If you'd like to contribute to Topside, please take a moment to read through this style guide. Otherwise, happy devving :)

Python

We generally conform to PEP8 guidelines for how we format our Python code. The repository contains a custom formatting script (tools/format.sh) - you should run this optionally before commits, and definitely before creating pull requests and/or merging to master.

When adding code, make sure to add unit tests to match! It's generally a good idea to run the full suite of unit tests before creating a PR (which can be done with the pytest command). If you don't, CI will run it for you, but it'll take much longer. This generally shouldn't be an issue, but please don't merge to master until the CI checks complete. We'll get a Slack notification if a failing build makes it to master, though, so don't be too scared of breaking things. They're always fixable :).

Qt/QML

Our QML code follows standard guidelines provided here.

Git

Generally, commit messages should follow guidelines laid out by Chris Beams here. Additionally,

  • Pull requests should be squashed and merged to be added as commits to master. If the PR pertains to code inside the topside/ directory (not the main repo), the commit message should be of the form <subsystem>: <Commit message>, where subsystem is the folder that the code is relevant to. Commit message is the commit message as normal, following regular message guidelines (capital first letter, no period, etc).

    An example commit message could be plumbing: Add solving algorithm, for a PR that affects code inside the topside/plumbing/ directory. Commit messages for code outside the topside/ directory don't need to follow this format. This is mainly to ensure that changes are immediately recognizable reading commit messages from the top level of the repository.

  • Version increments are done as standalone PRs. The commit message takes the form Designate <version> release (where version is the version), for example Designate 0.2.0 release. We add GitHub tags on these commits as well (for example, v0.2.0); these are visible under the releases tab.

    The workflow for incrementing a version is to upload to TestPyPi, create the PR, merge to master, then upload to actual PyPi. Steps for doing so are located here.

Clone this wiki locally