Contributor Guide¶
Thank you for your interest in PiperCI.
Getting Started¶
Follow the deployment instructions for the PiperCI Installer for the
Read Working with PiperCI Functions for more info on PiperCI functions.
Git Workflow¶
Use trunk-based development when proposing contributions to this repository. Submit your proposed change as a merge request from a feature branch in your fork.
Commit Message Guidelines¶
Always write clear commit messages.
We have very precise rules, following the Conventional
Commits
standard, that govern how commit messages may be formatted. This leads
to more readable messages that are easy to follow when looking
through the project history. But also, we use the commit messages to
generate the CHANGELOG
based on angularjs-style commits.
These rules are enforced across our projects by our CI pipelines using this commitchecker job commitlint
Commit Message Format¶
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read in the browser as well as in various git tools.
Revert¶
If the commit reverts a previous commit, it should begin with
revert:
, followed by the header of the reverted commit. In the body
it should say: This reverts commit <hash>.
, where the hash is the
SHA of the commit being reverted.
Type¶
Must be one of the following:
build: changes that affect the build system or external dependencies
ci: changes to our CI configuration files and scripts
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
docs: Documentation only changes
feat: A new feature
fix: A bug fix
perf: A code change that improves performance
refactor: A code change that neither fixes a bug nor adds a feature
revert: Reverting a previously committed change
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
test: Adding missing or correcting existing tests
Scope¶
The scope could be anything specifying place of the commit change. For
example $location
, $browser
, $compile
, $rootScope
,
ngHref
, ngClick
, ngView
, etc…
You can use *
when the change affects more than a single scope.
Subject¶
The subject contains succinct description of the change:
use the imperative, present tense: “change” not “changed” nor “changes”
don’t capitalize first letter
no dot (.) at the end
Body¶
Just as in the subject, use the imperative, present tense: “change” not “changed” nor “changes”. The body should include the motivation for the change and contrast this with previous behavior.
Tests¶
We use pytest
as our test automation framework. Generally, add
adequate unit tests under /tests/unit
per merge request.
Ensure your tests pass before submitting a merge request in the repository.
To run all tests you should use tox: tox
Going forward, functional (i.e., end-to-end) testing will also be done
using tox
Coding Style¶
Much of PiperCI is written in Python. For all Python code, we will
adhere to PEP8 with a few exceptions. For such exceptions, see the
python-project\tox.ini.example
configuration file.
We use flake8
for basic linting checks.
Coding Standards¶
Code is to run in Python 3.7.3
New code should use type hinting for external interfaces intended to be used by other developers. See: PEP 484
Merge requests must pass the standard linting.
DRY principles unless it doesn’t make sense.
Pytest coverage must be greater then
80%
All code must be contained in a valid module with an
__init__.py
Modules should make use of exceptions, functions should not introduce side effects… like
print()
orsys.exit()
Logging and debug should use the python standard
logging
library