Skip to content

Latest commit

 

History

History
218 lines (156 loc) · 6.88 KB

CONTRIBUTING.md

File metadata and controls

218 lines (156 loc) · 6.88 KB
Raw

Branch Naming Conventions

  • Choose short and descriptive names
  • Prefix branch names with corresponding issue numbers
  • Use hyphens to separate words
  • Use lower case only

Example: 123-my-feature.

Commit Message Conventions

These rules are adopted from the AngularJS commit conventions .

Goals

  • allow generating CHANGELOG.md by script
  • allow ignoring commits by git bisect (not important commits like formatting)
  • provide better information when browsing the history

Generating CHANGELOG.md

We use these two sections in changelog: new features and bug fixes. This list could be generated by script when doing a release. Along with links to related commits. Of course you can edit this change log before actual release, but it could generate the skeleton.

List of all subjects (first lines in commit message) since last release:

git log <last tag> HEAD --pretty=format:%s

New features in this release

git log <last release> HEAD --grep feature

Recognizing unimportant commits

These are formatting changes (adding/removing spaces/empty lines, indentation), missing semi colons, comments. So when you are looking for some change, you can ignore these commits - no logic change inside this commit.

When bisecting, you can ignore these by:

git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)

Provide more information when browsing the history

This would add kinda “context” information. Look at these messages (taken from last few angular’s commits):

  • Fix small typo in docs widget (tutorial instructions)
  • Fix test for scenario.Application - should remove old iframe
  • docs - various doc fixes
  • docs - stripping extra new lines
  • Replaced double line break with single when text is fetched from Google
  • Added support for properties in documentation

All of these messages try to specify where is the change. But they don’t share any convention...

Look at these messages:

  • fix comment stripping
  • fixing broken links
  • Bit of refactoring
  • Check whether links do exist and throw exception
  • Fix sitemap include (to work on case sensitive linux)

Are you able to guess what’s inside ? These messages miss place specification... So maybe something like parts of the code: docs, docs-parser, compiler, scenario-runner, …

I know, you can find this information by checking which files had been changed, but that’s slow. And when looking in git history I can see all of us tries to specify the place, only missing the convention.

Format of the commit message

[#<issue1>] [#<issue2>] <type>(<scope>): <subject>

A commit message should contain one line and should not be longer than 100 characters. This allows the message to be easier to read on github as well as in various git tools.

Referencing issues

Related issue(s), if any, should be listed in the beginning of a commit message.

Allowed <type>

This type should be assigned from the perspective of a customer, since these types end up in the changelog.

  • feat (feature)
  • fix (bug fix)
  • docs (documentation)
  • style (formatting, missing semi colons, …)
  • refactor
  • test (when adding missing tests)
  • chore (CI, builds, maintainance, …)

Allowed <scope>

Scope could be anything specifying place of the commit change.

Use a microservice name (or comma-separated microservice names, or a corresponding folder name like deployment , commons or scripts) as a scope.

Undefined (omitted) scope means that commit changes a lot of components at once (although ideally commits and PRs should not be huge).

<subject>

Subject line contains succinct description of the change.

  • use imperative, present tense: “change” not “changed” nor “changes”
  • don't capitalize first letter
  • no dot (.) at the end

Examples

#123 feat: anonymize tattoos and moles

#456 fix(face_generator): remove unnecessary highlights from faces

chore(deployment): make a new Docker image

Python Code Style Reference

Tests

All new features and bug fixes must be tested. If you add a new feature, please add unit and functional tests. If you fix a bug, add tests that check if it was fixed.

A "Best of the Best Practices" (BOBP) guide to developing in Python.

Formatting

To format code we use black.

NOTE: Make sure you are using the same version of the black as in the FormatGitHub actions. Different versions of black could format the code differently.

Use one of the following commands to format your changes before committing them:

  • black <python-file name or package path>
  • python -m black <python-file name or package path>

PEP8 complaince

To validate code's PEP8 complaince we use flake8.

Use one of the following commands to check complaince with PEP8 for your changes before committing them:

  • flake8 <python-file name or package path>
  • python -m flake8 <python-file name or package path>

Imports sorting

To sort imports we use isort.

Use one of the following commands to check complaince with PEP8 for your changes before committing them:

  • isort <python-file name or package path>
  • python -m isort <python-file name or package path>

Type annotations

We use type annotation for most of our code.

NOTE: Do NOT use Generics and parameterized generics in annotations. Use classical syntax.

For numpy arrays type annotations, please see numpy.typing

do this do NOT do this
Dict[str, int] dict[str, int]
Tuple[List[Dict[str, int]], ...] tuple[list[dict[str, int]], ...]
npt.NDArray[np.uint8] np.ndarray