Skip to content

Plugin Certification Program

Jump to bottom
Jeff Gehlbach edited this page May 8, 2024 · 9 revisions

Program goals

Put resources behind key plugins

The first priority of the plugin certification program is to mobilize resources from NetBox Labs to make the decision to use plugins an easy and confident one for the whole population of NetBox users. This resourcing takes several forms, including:

  • Defining attainable quality criteria for plugins to achieve certification
  • Facilitating the ongoing compatibility of certified plugin releases with NetBox
  • Facilitating the ongoing compatibility of NetBox releases with certified plugins
  • Assuring the maintainability of plugins by partnering with lead plugin maintainers
  • Offering commercial support for certified plugins when installed in qualified NetBox runtimes

Make finding and installing plugins easy

By investing in a catalog where all plugin maintainers can list their creations, we are removing the guesswork from finding plugins that help users accomplish their goals. We enable plugin authors to provide metadata concerning version capability, dependencies, and other key attributes, by making that catalog the singular place users need to go to identify which plugin releases will work with their NetBox instances.

Provide support and resources to plugin authors and maintainers

  • For all plugin makers (coming 2Q2024):
    • Updated cookiecutter template
    • Updated plugin author's guide
    • NetBox developer hub
  • For lead maintainers of certified plugins:
    • Offer of repo transfer to netbox-community
    • Private communication channels for maintainers of certified plugins
    • A safety net of backup maintainers whose job descriptions include helping out

Program mechanics

Eligibility criteria

License

To qualify for certification, a plugin must be available under an OSI-approved open-source license. NetBox plugins tend to import classes from the netbox.api and netbox.plugins namespaces, making a license that is compatible with the Apache License version 2.0 a practical requirement.

A copy of the plugin's license must be included at the top level of the plugin's source repository, in a file named LICENSE.md, LICENSE.txt, or LICENSE. The same license must be designated in the plugin's PyPI package entry.

Among licenses characterized by OSI as “popular / strong community”, the practical choices are, in rough order of recent popularity:

Note that versions of the LGPL, GPL, and MPL prior to the ones noted above are incompatible with the Apache-2.0 license used by NetBox, and are therefore not practical for licensing NetBox plugins.

Willingness to establish co-maintainer relationship

To deliver on the program's goal of compatibility, maintainability, and supportability, lead maintainers of all certified plugins must establish a co-maintainer relationship with the NetBox Labs engineering staff. The intention here is to add a pool of qualified maintainers who get paid to hack on NetBox and its ecosystem to each certified plugin's ranks. Most of the time they will be in the background. In case a critical bugfix or snap release is needed, and the lead maintainer is on holiday or otherwise unavailable, they will step into the foreground for as long as needed. The lead maintainer remains at the helm at all other times.

The co-maintainer relationship has two aspects: GitHub and PyPI.

GitHub

There are three ways to establish co-maintainer status for a plugin on GitHub under the program:

  • Preferred: Transfer the plugin's repo to the netbox-community GitHub org. Lead maintainer retains Maintain-level access granted via a GitHub Team which also includes NetBox Labs developers.
  • Alternate 1: Designate NetBox Labs staff as maintainers in lead plugin maintainer’s GitHub org. Lead maintainer grants Maintain-level access to NetBox Labs developers via a GitHub Team. This option may be a fit for plugins maintained by businesses with multiple developers already on their own staff.
  • Alternate 2: Designate NetBox Labs staff as collaborators in lead plugin maintainer’s personal GitHub profile. For lead maintainers whose plugins form a benefit to their reputation as freelance professionals, we are happy to have a few NetBox Labs developers designated as collaborators on the repository.

NOTE: Only GitHub-hosted plugins qualify at this time. Maintainers of plugins hosted elsewhere are nonetheless encouraged to apply.

PyPI

These steps enable publishing of the plugin’s PyPI artifacts by NetBox Labs staff via adding a publisher user to the project's PyPI listing in the Owner role. It is required for all certified plugins as a “break glass” mechanism in case a release needs to be published on short notice when the lead maintainer is unavailable. The plugin lead maintainer retains the Owner role alongside the publisher user; PyPI allows many users to have the Owner role for a given package.

NOTE: If and when PyPI unpauses applications for new organizations, this aspect will be reworked to take advantage of that facility.

Version compatibility metadata

Each release of a certified plugin must include metadata indicating which versions of NetBox are compatible with the plugin release. Currently this metadata is human-readable and lives in the plugin's top-level README. A schema for expressing this metadata in machine-readable form will be introduced once it has stabilized.

Test coverage

Every certified plugin must include a reasonably comprehensive set of tests which run as GitHub Workflows. Currently the standard for this requirement is subjective. Making it specific and measurable will follow. The plugin author's guide and cookiecutter template are being updated to put new plugins on a footing to align with this requirement.

NOTE: Only plugins using GitHub workflows for CI qualify at this time. Maintainers of plugins using other CI platforms are nonetheless encouraged to apply.

Documentation quality

Every certified plugin's documentation and release notes must meet minimum criteria for quality, including:

  • Plugin's top-level README should summarize the most salient points of its main documentation, and must include:
    • A headline summarizing the plugin's value
    • A concise introduction further breaking down the plugin's value so that a user can decide whether they might want to use it
    • A matrix of compatible plugin version ranges and NetBox version ranges
    • A list of any other NetBox plugins, Python libraries, external software, or external services that the plugin depends on for its operation, along with compatible version ranges for each such dependency. If no such dependencies exist, specify "None".
    • One or more screenshots or screen recordings illustrating the plugin's value (exceptions are possible in case of plugins with very limited scope)
    • Brief installation instructions which do not assume deep user familiarity with plugins generally, and which when followed exactly on a fresh installation of NetBox will result in a functioning plugin.
    • A summary of where and how to engage with the plugin's maintainer team for bug reports, feature requests, and documentation requests (GitHub issues, Slack, etc.)
    • A summary of where and how to seek support as a user of the plugin (GitHub discussions, Slack, etc.)
    • An icon which:
      • Has a square aspect ratio
      • Scales recognizably at sizes from 48x48px through 500x500px
      • Is licensed under a Creative Commons license that does not prohibit commercial use
      • Is provided as either SVG or PNG with transparency
  • The plugin's main documentation must treat each of the points in the README in further depth. To minimize redundancy, linking into the main documentation from the top-level README is encouraged, particularly concerning the concise introduction.
  • Plugin documentation may not consist solely of a top-level README unless the plugin's scope is exceptionally small.
  • Plugin's release notes must open with a brief narrative summary characterizing it as a major, minor, or patch release and indicating whether it consists of bug fixes, new features, enhancements to existing features, or all of the above.
  • Any time a release introduces breaking changes, the release notes must include a bold header reading Breaking Changes under which a brief summary of each such change is provided, including links to each relevant issue.
  • Plugin's release notes must include a changelog enumerating the issues resolved in the corresponding release.

The plugin author's guide and cookiecutter template are being updated to put new plugins on a footing to meet this requirement.

Obtaining certification

Apply for certification

If you are the lead maintainer of a NetBox plugin that you would like to submit for consideration, email [email protected] with a brief description of your plugin's purpose and a few sentences explaining why you are applying. Please also include the following details at minimum:

  • A link to the plugin's GitHub repo
  • A link to the plugin's PyPI package entry
  • Your GitHub ID
  • Your PyPI user ID
  • If you are reliably reachable on NetDev Slack, the name you go by there

A NetBox Labs representative will be in touch to get the process started.

Maintaining certification

Certification is conferred at the release level rather than the plugin level. To continue to be listed in the plugin catalog as Certified, a plugin release must meet the test coverage and documentation quality requirements outlined above. NetBox Labs staff will also validate each new release of a plugin for compatibility with a range of NetBox versions. As this human-driven process evolves, it will become more automated.

Terms subject to change

NetBox Labs may change the terms of the program as circumstances dictate. They promise not to be monsters about it.

Plugin Catalog

If your plugin isn't ready for certification but you would like to see it listed in the NetBox Labs plugin catalog, please email [email protected]. Please include the following information in your message:

  • Your name
  • The name you would like to see listed in the catalog for the plugin
  • The best email address to reach you about the plugin in question
  • A link to the plugin's source repo
  • A link to the plugin's PyPI package entry
  • The plugin's config name (the value you add to PLUGINS = [] in configuration.py when installing)
Clone this wiki locally