Zoidberg Packaging Guidelines

This document defines the official packaging guidelines for Zoidberg, the primary Zoi package registry. These standards ensure that Zoi remains a high-quality, secure, and consistent ecosystem for developers across Linux, macOS, and Windows.

Packages submitted to the core, main, and extra tiers must adhere strictly to these guidelines.

1. Inclusion Policy & Tiers

Zoidberg is dedicated to high-quality software that enhances the developer and system environment.

1.1. Tier Definition

• core: Essential packages and libraries. Very common, high stability, and well-maintained.
• main: Important packages that are essential for most users but don't fit in core.
• extra: Niche or specialized packages. Less common or less actively maintained.
• community: User-submitted packages. This is the starting point for most new submissions.
• test: For testing new Zoi features or packages before they graduate.
• archive: For software that is no longer maintained.

1.2. Licensing & Proprietary Software

• Open Source Preferred: Software in the core and main tiers MUST be licensed under an OSI-approved open-source license.
• Proprietary Consideration: Proprietary or "source-available" software may be considered for the community or extra tiers provided it is legally redistributable and clearly states its restrictions.
• Prohibited Content: Packages containing malware, spyware, offensive content, or software primarily intended for illegal activities are strictly prohibited.

2. Build Methodology: Binary-First

Zoidberg follows a Binary-First, Pragmatic Hybrid model.

2.1. Preference for Pre-compiled

To ensure fast and reliable installation for end-users, pre-compiled is the preferred build type. When available, a package should provide a pre-compiled type that downloads tested binaries from an upstream release.

2.2. Source Builds

Providing a source build type is highly encouraged as a secondary option. It provides transparency and allows for platform-specific optimizations.

2.3. Pragmatic Bundling (Vendoring)

• Shared Over Bundled: Prefer declaring dependencies via zoi:, native:, or ecosystem-specific managers instead of bundling them inside your package.
• Pragmatic Exception: Bundling (vendoring) is allowed when upstream makes it exceptionally difficult to separate dependencies, or for ecosystems where vendoring is the standard.

3. Naming & Versioning Standards

3.1. Flat Naming

Zoidberg uses a Flat Naming convention.

• Simplicity: Use the simplest, most common name for the software (e.g. ripgrep, not rust-ripgrep).
• Lowercase: All package names MUST be lowercase ASCII.
• Characters: Use only lowercase letters, digits, and hyphens (-). Avoid underscores or periods.
• Collision Handling: Collisions are handled on a case-by-case basis. If a name is already taken, prioritize the more popular or established tool.

3.2. Versioning (PKG.version)

The version field MUST match the upstream version verbatim.

• Prefixes: Strip any v prefixes (e.g. use 1.2.3 instead of v1.2.3).
• SemVer: Follow SemVer patterns where possible.

3.3. Revisions (PKG.revision)

The revision field tracks downstream changes to the package definition itself.

• Increment if you fix a bug in the Lua script, update a dependency, or change a configuration file while the upstream version remains the same.
• Reset to "1" whenever the upstream version is bumped.

4. Metadata & Quality Requirements

4.1. Required Fields

Every submission MUST include:

• name: The flat package name.
• repo: The targeted tier.
• version: Upstream version.
• description: A concise, one-line summary.
• license: A valid SPDX license identifier.
• maintainer: Name and email of the package maintainer.

4.2. Recommended Testing

Implementing a test() lifecycle function is highly recommended for the core and main tiers, and strongly encouraged for all others. The test should verify that the binary executes correctly (e.g. running myapp --version).

function test()
  local _, _, code = cmd("${pkgstore}/bin/myapp --version")
  return code == 0
end

5. Dependency Management

5.1. Manager Hierarchy

When resolving dependencies, use the following priority:

1. zoi:: For other Zoi-native packages.
2. native:: For core system libraries (like openssl) to ensure host compatibility.
3. Language Managers: Use npm:, cargo:, pip:, etc., for tools specific to those ecosystems.

5.2. No Direct Internet in Build/Package

Lifecycle functions like build() and package() SHOULD NOT access the internet. All downloads MUST happen in prepare().

6. Integration & Security

6.1. Shell Integration

Use the zshell() helper function to bundle completion scripts for Bash, Zsh, and Fish.

6.2. License Staging

Every package MUST stage its license text to the package store using the zlicense() helper.

function package()
  -- Stage binary...
  zcp("bin/tool", "${pkgstore}/bin/tool")
  -- Stage license
  zlicense("LICENSE")
end

6.3. Security Verification

• Hashes Required: All pre-compiled downloads MUST be verified using verifyHash() with a strong algorithm (sha512 or sha256).
• Signatures: Use verifySignature() with upstream PGP keys whenever available.

7. Submission Process

Before submitting a Merge Request:

1. Linter: Run zoi package doctor on your script.
2. Test: Run zoi package test locally.
3. Inspect: Run zoi package inspect --json to verify resolved metadata.

For a detailed step-by-step on contributing, see the CONTRIBUTING.md.