Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
110 lines (75 loc) · 8.66 KB

CONTRIBUTING.md

File metadata and controls

110 lines (75 loc) · 8.66 KB
Raw

Contributing a plugin to the catalog

Listing a plugin takes a public GitHub repository, a GitHub release holding a wheel or a single Python file, and a pull request adding one YAML entry. No PyPI account is needed. Single-file artifacts are supported by the updated Desktop client only, not DataLab-Web.

Requirements

  • The source code is public on GitHub and licensed under an OSI-approved license. A wheel declares its license in its metadata (license = "..." in pyproject.toml with setuptools 77 or later); a module declares its SPDX license identifier in the catalog entry and must have corresponding source licensing. Accepted licenses: 0BSD, AFL-3.0, Apache-2.0, BSD-2-Clause, BSD-3-Clause, BSL-1.0, CECILL-2.1, EPL-2.0, EUPL-1.2, GPL-2.0 and 3.0, ISC, LGPL-2.1 and 3.0, MIT, MPL-2.0, PSF-2.0, Unlicense, Zlib.
  • The artifact is either a pure-Python wheel (*-py3-none-any.whl) or one importable datalab_<name>.py source file (maximum 4 MiB), without compiled plugin code.
  • A wheel declares its plugin class in the datalab.plugins (Desktop) and/or datalab.web_plugins (Web) entry-point group. A module uses Desktop's existing file-name convention and plugin API; it does not need an entry-point file or packaging metadata.
  • Its requirements must be satisfied by DataLab (for example datalab-platform, sigima, numpy, scipy) or, for Desktop, by explicitly listed dependency wheels. Existing host package versions cannot be replaced. Additional wheels may contain native libraries but must cover the intended Python/ABI/platform; no compilation or system installation is performed. Web requirements remain restricted to packages supplied by the Web host.
  • The entry's ID agrees with a statically readable PluginInfo.id when present. For an unchanged historical module with unavailable metadata or several plugin classes, the entry identifies the entire module without rewriting its runtime identities. Prefer a reverse-domain name that you control, such as io.github.<your-account>.<plugin>. The org.datalab. prefix is reserved for DataLab-Platform plugins.

The generators datalab-plugin create and create --project provide a starting point for the two source forms. Catalog metadata must still be supplied when it is not in the artifact.

Source organization is not the distribution format

A plugin may be developed as a single datalab_<name>.py module or as a larger Python package. Both use the same plugin API and may expose the same functional capabilities. The layered project generated by datalab-plugin create --project is one convenient organization, not a catalog requirement.

The catalog accepts both wheels and raw single-file Desktop plugins. A wheel may contain just one module: packaging it does not require adopting the layered project. A raw .py entry avoids that packaging step entirely.

Listing a single-file Desktop plugin

Attach the unchanged datalab_<name>.py file to a versioned GitHub release, then add a YAML entry such as:

id: io.github.alice.spectrum-tools
name: Spectrum Tools
kind: module
summary: Spectral processing in one Python file
license: BSD-3-Clause
repository: https://github.com/alice/spectrum-tools
capabilities: [processing]
releases:
  - version: "1.0.0"
    filename: datalab_spectrum_tools.py
    sha256: <SHA-256 of the actual file>
    requires_python: ">=3.10"

filename selects an exact release asset and stays stable between versions; do not add version numbers or hyphens that make the Python module name invalid. summary, license and a release version are required in the public entry. Literal source identities and versions, when readable, must agree with the entry. Unknown metadata is not evaluated: constructors, dynamic expressions and plugin code are never executed during inspection. A syntactically valid module is not thereby certified as a working or safe plugin.

Modules use already available Desktop libraries. They cannot declare dependency wheel installation, use PyPI as their artifact source or advertise the Web target. The catalog mirrors their exact bytes under modules/<sha256>/; copying that tree and catalog.json provides an offline mirror. Local catalogs may also scan .py and .whl files directly at the root, without an index.

For a local module whose version is unavailable, the generated index keeps an empty version. Desktop compares digests and asks for explicit replacement when content changes, rather than inventing a newer version. Local catalog build/check/prepare commands include modules, but only wheels participate in dependency preparation. Descriptive metadata supplied in an existing local JSON index is preserved when it is rebuilt.

Additional Desktop dependencies

Put the plugin wheel in a local catalog folder and run datalab-plugin catalog prepare <folder> from the target reference environment. This authoring command uses pip to resolve and download missing dependencies, including transitive dependencies, into the folder's dependencies subdirectory without installing them. It prints the dependency_wheels YAML entries to add to the plugin release. Preparing the wheelhouse needs network access; installing the complete local catalog does not.

Each dependency entry names its wheel, upstream HTTPS URL and reviewed SHA-256:

releases:
  - version: 1.0.0
    sha256: <plugin digest>
    dependency_wheels:
      - filename: example_dependency-1.0.0-py3-none-any.whl
        url: https://files.example.org/example_dependency-1.0.0-py3-none-any.whl
        sha256: <dependency digest>

The CI checks and mirrors these artifacts without executing them. The Desktop client downloads only compatible wheel tags, verifies the files, and resolves against its actual host using the local wheelhouse only. A missing transitive artifact or version conflict causes a refusal, not an implicit download from PyPI. Prepare and include wheels for each intended environment; do not assume that one native wheel supports all desktop installations. Respect the redistribution, license-notice and corresponding-source obligations of every dependency.

Submitting a plugin

The following is the wheel workflow; single-file authors use the release asset and entry described above instead.

  1. Build the wheel (python -m build) and attach it to a GitHub release of your repository, tagged v<version> (for example v1.0.0).

  2. Fork this repository and add plugins/<id>.yaml:

    # yaml-language-server: $schema=../schema/plugin-entry.schema.json
id: io.github.alice.spectrum-tools
name: Spectrum Tools
repository: https://github.com/alice/datalab-spectrum-tools
capabilities: [processing]
keywords: [spectroscopy, baseline]
releases:
  - version: 1.0.0

  3. Open a pull request. The CI downloads and checks the wheel. The first run fails and prints the line to add to the release, such as sha256: 3f2a...: add it and push again.

A wheel published on PyPI may be listed instead of a GitHub release asset, with source: pypi and distribution: <name> in the release.

Optional icon

To display an existing plugin icon in the web catalog, add its HTTPS image URL once, at the plugin level:

icon: https://raw.githubusercontent.com/alice/datalab-spectrum-tools/main/src/spectrum_tools/icons/plugin.svg

SVG and PNG are recommended; any image format supported by browsers may be used. On GitHub, use the raw file URL, not a github.com/.../blob/... page. No particular file name, location or hosting provider is required, and there is no need to copy the image here or publish a new plugin version.

The browser loads the icon directly from its host, without sending a referrer. The catalog build does not download or check the image. Initials are displayed when no icon is declared, when it cannot be loaded, or when JavaScript is disabled. If the file moves, update its URL; a branch URL can update the icon independently of plugin releases, subject to browser caching.

Publishing a new version

Add the version, with its sha256, at the end of releases and open a pull request. Every new version is reviewed before it is published: keep the previous versions listed.

Withdrawing a version or a plugin

  • yanked: <reason> in a release tells DataLab not to install it.
  • status: deprecated with a status_reason keeps the plugin installable with a warning.
  • status: revoked with a status_reason removes the downloads; DataLab warns users who installed the plugin. Maintainers revoke plugins that are malicious or seriously broken.

Review

Maintainers check that the entry is consistent, that the plugin matches its description, and that nothing in the repository is obviously harmful. This review is not a security audit: users are told to install only plugins from authors they trust.