Developer guide

In order to get your component added to the relevant official list on the Asphalt wiki, the library developer is required fulfill the requirements described in this guide. This seems like a harsh requirement but it establishes strict quality guarantees that make the life of application developers easier (which is the whole point of this thing anyway).

Project name

The library must conform to the naming convention of "asphalt-foo" where "foo" is a lowercase name for this specific library. If you project provides a plugin for an extension or application type, use a name like "asphalt-foo-bar" where "foo" is the library you're extending and "bar" is the name of your component.

Versioning

The versioning scheme must use semantic versioning 2.0. In other words, it must conform to the scheme of MAJOR.MINOR.PATCH, e.g. "1.2.3". If there is a conflict between the aforementioned document and this chapter, this text of this chapter is to be considered authoritative.

If a new version breaks the API, the MAJOR version number must be incremented. As a rule of thumb, if your changes potentially cause existing code (that relies on the public API) to stop working, it is considered a break of the API and requires a MAJOR version bump.

Changes that require a bump in the MAJOR version:

• removing packages, modules, classes, functions, methods or attributes
• renaming or removing function/method parameters
• narrowing the accepted input types for function/method parameters (e.g. dict ⟶ OrderedDict)
• broadening the return types of functions/methods (e.g. OrderedDict ⟶ dict)

Changes that require a bump in the MINOR version:

• renaming packages, modules, classes, functions, methods or attributes (requires an alias to be left in place which emits a DeprecationWarning if possible)
• adding new packages, modules, module variables, classes, class/instance attributes, or functions
• adding new optional arguments to a function/method (adding mandatory ones require a MAJOR version bump)
• making existing parameters optional
• broadening the accepted input types for function/method parameters

Only bug fixes are permitted when bumping the PATCH version. No changes in the API or semantics are allowed, unless there is a clear error, such as a typo. For example, if there was a typo in the name of a method, you need to keep the old name around as an alias for the new one up until the next MAJOR version bump. The alias must emit a DeprecationWarning indicating that the developer should use the renamed one.

NOTE: The above rules only apply to the documented API. Changes to the internal API are allowed at any point.

Version control

The library code must be stored in git, mercurial or similar distributed version control system. The main repository must be publicly accessible. It is recommended to use either Github or Bitbucket for this purpose. The location of this repository must be clearly indicated in the documentation and must be present on the PyPI page.

Code style

All of the library code, including command line scripts and tests, must adhere to the PEP 8 coding conventions. The extended 99 column limit applies. The code base must pass a flake8 run with the max-line-length = 99 option set. The same line length limit applies to the documentation.

Writing tests

The library must have a meaningful test suite. The library must provide a Tox configuration. The test suite is allowed to depend on a particular test runner. It is recommended, but not required, to use py.test as the test runner. The test suite must pass on every Python version supported by the Asphalt core version that your library depends on.

Documentation

Extensions must provide, at minimum, a basic README describing the purpose of the extension, its allowed configuration options and default values and minimal usage examples for major use cases. It is recommended to use reStructuredText as the documentation format.

For nontrivial libraries, proper, structured documentation must be provided. It is recommended to use Sphinx for this purpose, and to host the documentation at ReadTheDocs.

Application types must additionally provide a reasonable amount of runnable example code in the source tarball.

Packaging and publishing

The source distribution must contain at least the following files in the root:

• pyproject.toml
• LICENSE
• version control ignore file (.gitignore, .hgignore or similar)

The project metadata should contain at least the following information:

• project name and version
• author name
• short and long descriptions
• classifiers:
  • development status (production/beta/alpha)
  • license
  • supported Python versions (including Programming Language :: Python :: 3)
• install dependencies (including Asphalt core (asphalt))

When declaring the dependency to Asphalt libraries, they should be restricted to only the major versions the libraries it was tested against. As for other dependencies, the developer should make an effort to protect end users against API breakage caused by changes in the APIs of third party libraries. Unfortunately since most libraries don't declare any versioning policy, establishing compatibility guarantees may sometimes be impossible.

When publishing a new release on the Python Package Index, the developer must upload both a source tarball and a wheel. It is recommended to use the twine tool for this purpose. For projects that produce platform specific binary wheels, it is recommended to provide wheels for:

• Linux (manylinux2014 or later)
• Windows (32 and 64 bit)
• macOS (at least for the commonly deployed versions at the time)

...for all supported Python versions.

For more information on packaging and distribution, see the Python packaging guide.