Publishing Interfaces

Overview

After creating a new interface or a new version of an existing interface, you need to publish it to make it available to other developers. This process involves updating the interface manifest in the git repository.

Understanding interface manifests

Every interface in the AntelopeJS ecosystem has a manifest file (manifest.json) that defines its properties, versions, and implementations. This manifest is stored in the git repository under the interfaces/<interface-name>/ directory.

Manifest structure

{
  "description": "A brief description of what the interface does",
  "versions": ["beta", "1"],
  "modules": [
    {
      "name": "module-name",
      "source": {
        "type": "package",
        "package": "@organization/module-package",
        "version": "1.0.0"
      },
      "versions": ["beta", "1"]
    }
  ],
  "files": {
    "beta": {
      "type": "git",
      "remote": "[email protected]:Organization/interface-repo.git",
      "path": ".antelope/output/interface-name"
    },
    "1": {
      "type": "local",
      "path": "interfaces/interface-name/1"
    }
  },
  "dependencies": {
    "beta": {
      "packages": ["[email protected]"],
      "interfaces": ["other-interface@beta"]
    },
    "1": {
      "packages": ["[email protected]"],
      "interfaces": ["[email protected]"]
    }
  }
}

Key manifest properties

File types for different versions

The files property in the manifest can specify two different types of sources for interface definition files:

{
  "files": {
    "beta": {
      "type": "git",
      "remote": "[email protected]:Organization/interface-repo.git",
      "path": ".antelope/output/interface-name"
    },
    "1": {
      "type": "local",
      "path": "interfaces/interface-name/1"
    }
  },
  "dependencies": {
    "beta": {
      "packages": ["[email protected]"],
      "interfaces": ["other-interface@beta"]
    },
    "1": {
      "packages": ["[email protected]"],
      "interfaces": ["other-interface@1"]
    }
  }
}

For publishing an official interface version, you must:

1. Use the local type in the manifest
2. Include the interface definition files in the interfaces repository
3. Provide the relative path to these files in the manifest

This ensures that stable versions have all their files stored directly in the interfaces repository rather than depending on external repositories that might change. It also allows for proper code review of interface definitions before they become official, ensuring quality and consistency across the ecosystem.

Creating or updating an interface manifest

ajs module exports generate

Registering module implementations

If you've developed an alternative implementation of an existing interface, you need to update the manifest to include your module.

Add your module to the modules array with:

{
  "name": "your-module-name",
  "source": {
    "type": "package",
    "package": "@your-org/your-module-package",
    "version": "1.2.0"
  },
  "versions": ["beta", "1"]
}

Interface version review process

The review process for interface versions varies depending on whether they are development, beta, or official versions:

      
flowchart TD
    A[Create New Interface Version] --> B{What Version?}
    B -->|dev/beta| C[No Formal Review Required]
    C --> E[Update Files in Your Repository]
    E --> F[Reference via 'git' Type in Manifest]
    F --> G[Can Be Modified Later]
    B -->|official| D[Requires Full Review]
    D --> H[Submit Files to Interfaces Repository]
    H --> I[Reference via 'local' Type in Manifest]
    I --> K[Submit Documentation]
    K --> J[Code Review Process]
    J --> L{Approved?}
    L -->|No| N[Revisions Needed]
    N --> J
    L -->|Yes| M[Merged to Main Branch]
    M --> O[Official Version Published]
    O --> P[Future Changes Require New Version]
    style D fill:#f9d5e5
    style C fill:#eeeeee
    style G fill:#d5f5e3
    style P fill:#d5f5e3
    style K fill:#d5e8f9

    

Documentation requirements for official versions

When submitting an official version for review, you must include proper documentation:

• For new interfaces: Create a new documentation repository with comprehensive guides, examples, and API references
• For new versions of existing interfaces: Submit a PR to the interface's documentation repository with updated documentation that covers all changes and additions

Documentation should include:

• Interface purpose and key concepts
• API reference for all exported types and functions
• Example code demonstrating common use cases
• Migration guides when upgrading from previous versions

The documentation will be reviewed alongside the interface code as part of the approval process. Insufficient documentation may result in the version being rejected until proper documentation is provided.

If changes are needed after an official version is published, a new version must be created, following the same process.

Configuring git interface repository

The AntelopeJS CLI uses a default git repository for interfaces, but you can configure it to use a different one. This is particularly useful in several scenarios:

Setting a custom repository

To use your own interface repository as the default:

ajs config set git <repository-url>

Using alternate repositories for specific interfaces

Developers can also import specific interfaces from alternate repositories without changing their default configuration:

ajs module imports add interface-name --git <repository-url>

Viewing current configuration

To check which interface repository is currently being used:

ajs config get git

For more information on CLI configuration, see the CLI configuration documentation.

Best practices

• Test your interface thoroughly before publishing
• Include comprehensive documentation for your interface
• Provide clear descriptions for interfaces and modules
• Properly specify all dependencies required by your interface