Developer guide

In order to get your extension or application type 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 extension.

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 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:

• renaming or 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. OrderectDict ⟶ dict)
• broadening the return types of functions/methods (e.g. dict ⟶ OrderedDict

Changes that require a bump in the MINOR version:

• 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 100 column limit applies. The code base must pass a flake8 run with the max-line-length = 100 option set. The same line length limit applies to the documentation.

Interfaces

Respect the interfaces. If a parameter has been annotated to take values of a certain type, don't try to use properties or methods beyond what that class declares. Conversely, add type hints to all of your code. Use the @typechecked decorator in all code that is not performance critical. Declare your own interface classes when applicable.

Writing tests

The library must have a meaningful test suite. It is recommended, but not required, to use py.test as the test runner. 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.rst 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:

• setup.py
• tox.ini
• LICENSE.txt
• version control ignore file (.gitignore, .hgignore or similar)

The setup.py file should declare at least the following:

• 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 both Windows (32 and 64 bit) and Mac OS X, for all supported Python versions.

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