# at.happyproto.registry.promoteRelease

> Published by [happyproto.at](https://lexicon.garden/identity/did:plc:mo7vq4jbioxwafy5zkcc3eux)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:mo7vq4jbioxwafy5zkcc3eux/at.happyproto.registry.promoteRelease)
- [Documentation](https://lexicon.garden/lexicon/did:plc:mo7vq4jbioxwafy5zkcc3eux/at.happyproto.registry.promoteRelease/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:mo7vq4jbioxwafy5zkcc3eux/at.happyproto.registry.promoteRelease/examples)

## Definitions

### `at.happyproto.registry.promoteRelease`

**Type**: `procedure`

Publish an existing version's artifact under a new version, such as `1.2.0-rc.1` as `1.2.0`, without uploading it again. The new software.release.version points at the existing manifest. Optionally moves a channel to it and adds a changelog.

#### Input

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `changelog` | `string` | No | Release notes as CommonMark. The registry writes them to the caller's repo as a site.standard.document and links it from the version. |
| `fromVersion` | `string` | Yes | The published version whose manifest the new version reuses. |
| `name` | `string` | Yes | The project's name, which is the record key of its software.release.project: 1 to 64 lowercase letters, digits and interior hyphens. |
| `track` | `string` | No | A channel to move to the new version. No channel moves when absent. |
| `version` | `string` | Yes | The new version. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `changelog` | `ref` → `at.happyproto.registry.defs#ref` | No | The changelog's site.standard.document, when a changelog was given. |
| `channel` | `ref` → `at.happyproto.registry.defs#ref` | No | The software.release.channel, when track was given. |
| `resumed` | `boolean` | No | True when the new version already existed on the same manifest, so this call only finished what an earlier one started. |
| `version` | `ref` → `at.happyproto.registry.defs#ref` | Yes | The new software.release.version. |

#### Errors

- **AuthRequired**: The caller's identity could not be determined, so there is no repo to write to.
- **NotConfigured**: The registry has no identity configured. An operator problem, not a caller's.
- **InvalidRecord**: The input breaks a rule the registry applies, so it would refuse the records. The message names the field.
- **Upstream**: A record could not be written to the caller's repo. Records written before the failure stay, and the same call can be made again.
- **ProjectMissing**: The caller has no project of that name, or the registry has not indexed its at.happyproto.registry.project record. Call putProject first.
- **VersionNotFound**: fromVersion is not an indexed version of the caller's project.
- **VersionExists**: The new version is already published. A version never changes once published.
- **NotInstallable**: track was given, but the project is unavailable or retired, so a channel cannot point at the new version.

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "Publish an existing version's artifact under a new version, such as `1.2.0-rc.1` as `1.2.0`, without uploading it again. The new software.release.version points at the existing manifest. Optionally moves a channel to it and adds a changelog.",
      "errors": [
        {
          "description": "The caller's identity could not be determined, so there is no repo to write to.",
          "name": "AuthRequired"
        },
        {
          "description": "The registry has no identity configured. An operator problem, not a caller's.",
          "name": "NotConfigured"
        },
        {
          "description": "The input breaks a rule the registry applies, so it would refuse the records. The message names the field.",
          "name": "InvalidRecord"
        },
        {
          "description": "A record could not be written to the caller's repo. Records written before the failure stay, and the same call can be made again.",
          "name": "Upstream"
        },
        {
          "description": "The caller has no project of that name, or the registry has not indexed its at.happyproto.registry.project record. Call putProject first.",
          "name": "ProjectMissing"
        },
        {
          "description": "fromVersion is not an indexed version of the caller's project.",
          "name": "VersionNotFound"
        },
        {
          "description": "The new version is already published. A version never changes once published.",
          "name": "VersionExists"
        },
        {
          "description": "track was given, but the project is unavailable or retired, so a channel cannot point at the new version.",
          "name": "NotInstallable"
        }
      ],
      "input": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "changelog": {
              "description": "Release notes as CommonMark. The registry writes them to the caller's repo as a site.standard.document and links it from the version.",
              "maxGraphemes": 20000,
              "maxLength": 200000,
              "type": "string"
            },
            "fromVersion": {
              "description": "The published version whose manifest the new version reuses.",
              "maxLength": 64,
              "minLength": 1,
              "type": "string"
            },
            "name": {
              "description": "The project's name, which is the record key of its software.release.project: 1 to 64 lowercase letters, digits and interior hyphens.",
              "maxLength": 64,
              "minLength": 1,
              "type": "string"
            },
            "track": {
              "description": "A channel to move to the new version. No channel moves when absent.",
              "knownValues": [
                "latest",
                "beta",
                "alpha"
              ],
              "type": "string"
            },
            "version": {
              "description": "The new version.",
              "maxLength": 64,
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "name",
            "fromVersion",
            "version"
          ],
          "type": "object"
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "changelog": {
              "description": "The changelog's site.standard.document, when a changelog was given.",
              "ref": "at.happyproto.registry.defs#ref",
              "type": "ref"
            },
            "channel": {
              "description": "The software.release.channel, when track was given.",
              "ref": "at.happyproto.registry.defs#ref",
              "type": "ref"
            },
            "resumed": {
              "description": "True when the new version already existed on the same manifest, so this call only finished what an earlier one started.",
              "type": "boolean"
            },
            "version": {
              "description": "The new software.release.version.",
              "ref": "at.happyproto.registry.defs#ref",
              "type": "ref"
            }
          },
          "required": [
            "version"
          ],
          "type": "object"
        }
      },
      "type": "procedure"
    }
  },
  "id": "at.happyproto.registry.promoteRelease",
  "lexicon": 1
}
```