Project conventions

This document describes the common conventions for all projects contained in RPA Framework. All repositories and libraries which are part of the project should follow the conventions to make maintenance and bootstrapping easier.

Naming

All libraries in the framework are named with a shared convention. This convention is the prefix rpaframework-*, for example rpaframework-secrets for a secrets management library. This name is used for both the git repository and PyPI package.

Packages released under the framework will be in a shared Python namespace, which is currently RPA.

Version Control

All sources, i.e. code, documentation, examples, will be hosted in Github. These repositories will be public and available for inspection and forking by other users. They will be contained in Robocorp’s Github organization.

Availability

The primary source for RPA Framework libraries is the Python Package Index (PyPI). Packages should be reserved according to the Naming policy. Packages should also include the correct trove classifiers to make finding them easier.

Documentation

All libraries will have public documentation that includes both technical API documentation and (simple) usage instructions.

Documentation will be available in Github Pages, which will handle hosting.

Library documentation will be stored in version control and will be generated by Sphinx. Both Python and Robot Framework API documentation will be autogenerated from source files. The primary docstring format for libraries is reStructuredText.

The documentation will also include examples usages for both Python and Robot Framework. In-depth guides will be available separately in the Portal.

Creating documentation will be the responsibility of the library developer.

Code Formatting

All Python code should be automatically formatted using the Black tool. For convention issues which are not strictly formatting, flake8 is used. On top of this, we use Pylint and even isort or mypy.

These conventions should be validated for all pull requests. The project should probably offer a pre-commit hook which checks them automatically.

Reasons why auto-formatting is a good idea, from a similar Javascript tool: Why Prettier?

Testing

All libraries should have decent test coverage through unittests. The main tool for creating unittests is pytest. Coverage should also be tracked automatically, and this can be done via a pytest plug-in.

Each repository should also include example Robot Framework tasks that use the provided keywords. These examples can be used in the documentation, but they should also act as runnable acceptance tests.

In addition to functional testing, libraries should be validated according to common coding conventions.

Continuous Integration

All commits and pull requests should be validated automatically. The current best tooling option is Github Actions.

Validation steps should include at least formatting, unittests, and packaging.

The CI pipeline is a matrix of the following:

  • Platforms:

    • Windows

    • Linux

    • MacOS

  • Python versions:

    • Python 3.8

    • Python 3.9

    • Python 3.10

Change Log

All packages should keep track of changes. This includes all additions, removals, changes, bug fixes etc. that affect users. All created releases should contain a change log entry.

Change logs are meant to be human-readable and generating them from git log entries is not an acceptable method. The process can be entirely manual or rely on tools such as towncrier.

Versioning

Semantic versioning is used when creating packages. The gist of it is as follows:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards compatible manner, and

  • PATCH version when you make backwards compatible bug fixes.

Other issues

Type hinting

Type hinting is supported since Python 3.6 and improves the maintainability of projects after they reach a certain size. Hints are also used by Robot Framework to automatically convert input arguments from keywords.

All keyword libraries should strive to add type hinting and they should be validated with a tool such as mypy.

Note

Type hints are not supported by Python versions older than 3.6. The RPA Framework project aims to support versions 3.6 and newer, but if required, the hinting features are available through a backport package.