# Plugins Index

## Summary

This document proposes an official conda plugins index. It covers how the index works, how plugins can be added to it and which group will be responsible for maintaining it. This proposal is split into two different sections, “Technical implementation” which covers the technical details for how plugins are managed and discovered by conda users and “Maintainers” which covers the group of people ultimately responsible for maintaining this plugin index and their decision making process.

## Technical implementation

The technical implementation of the plugins index consists of two components: the server where the index is to be hosted (a simple JSON file) and the client which will consume this file. Below is a description of these components work.

### Server

The plugins index will be hosted as a JSON file at conda.org at the following URL:

- https://plugins.conda.org/plugins.json

The schema file defining the layout of this file will be hosted at:

- https://plugins.conda.org/plugins.schema.v1.json

The v1 schema will be defined as follows:

{
  "$schema": "http://json-schema.org/draft/2020-12/schema",
  "$id": "https://plugins.conda.org/plugins.schema.v1.json",
  "title": "Plugins Index Schema v1",
  "description": "Schema definition for the plugins.json file",
  "type": "object",
  "properties": {
    "plugins": {
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "required": [
          "name",
          "description",
          "website"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "minLength": 1
          },
          "website": {
            "type": "string",
            "minLength": 1
          },
          "channels": {
            "type": "array",
            "uniqueItems": true,
            "minItems": 1,
            "items": {
              "required": [
                "name",
                "package_name"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1
                },
                "package_name": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          }
        }
      }
    }
  },
  "required": [
    "plugins"
  ]
}

An example of what `plugins.json` looks like:

{
  "plugins": [
    {
      "name": "conda-auth",
      "description": "Plugin for enhanced authentication handling",
      "website": "https://github.com/conda-incubator/conda-auth",
      "channels": [
        {
          "name": "defaults",
          "package_name": "conda-auth"
        },
        {
          "name": "conda-forge",
          "package_name": "conda-auth"
        }
      ]
    }
  ]
}

Clients will have the ability to consume both the `plugins.json` and `plugins.schema.v1.json` to display information about available plugins and verify the schema of the `plugins.json` file, respectively.

#### Updating the index

The index will be manually updated, and each new addition will be made via a pull request to the [plugins](https://github.com/conda-incubator/plugins) repository. A check will be added to this repository so that the `plugins.json` file is validated against the `plugins.schema.v1.json` file. This will ensure no errors in formatting or content are introducing while manually editing this file.

A discussion on exactly who must approve these changes follows in the "Maintainers" section.

### Client

For the client, we will be focusing entirely on the `conda` CLI tool. A new subcommand will be added to conda to allow users to discover plugins (`conda plugins list`). The updates to the client will keep the following goals in mind described as user stories:

1. As a user, I want to be able to list my currently installed plugins
2. As a user, I want to see a list of all available plugins and know which ones I currently have installed
3. As a user, I want to be able to easily discover new plugins, read brief descriptions about and learn where I can find more information on them
4. As a user, I want to be able to install a plugin
5. As a user, I want to be able to remove a plugin

#### Discovering plugins

For items 1-3, we will be adding a new `conda plugins list` command that will download the `plugins.json` file and display a list of all plugins contained within. A listing of the base environment will be referenced to see which plugins are currently available. This information will be made available to the user.

An example of what the output of that command could look like is shown below:

$ conda plugins list

name: conda-auth
description: Conda plugin for various conda auth handlers
website: https://github.com/conda-incubator/conda-auth
available at: conda-forge::conda-auth, defaults::conda-auth
installed: no

...

#### Managing plugins

For items 4 and 5, we will rely on the existing `conda install` and `conda remove` commands. In the future, we may wish to add new subcommands under the `conda plugins` namespace for this purpose (e.g. `conda plugins add <plugin>` and `conda plugins remove <plugin>`).

## Maintainers

To help manage the plugin index, a new sub-team will be formed. This process is currently underway and can be tracked here:

- https://github.com/conda/governance/issues/77

### Rules for adding/removing plugins to the index

For adding/removing plugins to the index the maintainers will adhere to one of the following rules:

- Atleast 3 members voting, with all votes being "yes"
- Atleast 50% participation, with greater than 50% "yes" votes to pass

*These rules were copied from the [Nominate new member of a Community Project Team](https://github.com/conda/governance?tab=readme-ov-file#nominate-new-member-of-a-community-project-team) section of the conda goverance document*

The votes will occur via pull requests in the [plugins](https://github.com/conda-incubator/plugins) repository and a special "conda-plugins-index" team will be assigned to review these pull requests. Each approval on the pull request will count as a single "yes" vote. A "request for changes" on the pull request will be counted as a single "no" vote.

#### Examples

Below are some practical examples of how voting may turn out with various team sizes:

- 3 team members with all votes being yes; passing :heavy_check_mark:
- 3 team members with one yes vote and two no votes; not passing :negative_squared_cross_mark:
- 3 team members with two yes votes and one no vote; passing :heavy_check_mark:
- 3 team members with two yes votes and one absentee vote; passing :heavy_check_mark:
- 5 team members with three yes votes and two no votes; passing :heavy_check_mark:
- 5 team members with three yes votes and two absentee votes; passing :heavy_check_mark:
- 5 team members with two yes votes and three absentee votes; not passing :negative_squared_cross_mark: