# App versioning

## What a version contains

Each version is a snapshot of the following information at the time you submit it:

* Version tag (Semantic Versioning)
* Release notes (update notes)
* Granted scopes (requested permissions)
* Availability/Members (who can access during validation)

These fields are displayed in the version form:

* App version: required. Use Semantic Versioning, for example `1.0.0`.
* Update Notes: required. Short, user-facing change log for this version (up to 500 characters).
* Scope changes: list of tenant token scopes requested by the app. You can add/remove scopes here. If a required data permission is missing, you will be prompted to configure it before submission.
* Availability → Members: choose which members can access the version while it is under review or in private testing.

## Semantic Versioning (required)

Use MAJOR.MINOR.PATCH:

* MAJOR (X.0.0): incompatible changes, new required scopes, or breaking API/behavior changes.
* MINOR (x.Y.0): backwards‑compatible feature additions or new optional scopes.
* PATCH (x.y.Z): backwards‑compatible bug fixes and improvements only; no new scopes.

Examples: `1.0.0` → initial release; `1.1.0` → new features; `1.1.1` → bug fix.

## Version status lifecycle

A version moves through these states:

| Status           | Description                                                                                    | Limit                                                                                                               |
| ---------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Draft            | Created by the developer; fields can be freely edited.                                         | Not public; editable (including scopes and members); not publishable until submitted.                               |
| Pending approval | Submitted by the developer; waiting in the queue.                                              | Read‑only for developer (except Cancel); scopes/members locked; not live.                                           |
| In review        | Marketplace admin is actively reviewing.                                                       | Read‑only for developer (except Cancel); any change requires returning to Draft.                                    |
| Approved         | Review passed; the version is eligible to be published.                                        | Read‑only; not live until Publish.                                                                                  |
| Published        | The version is live and visible to target users.                                               | <p>Immutable; scopes/notes cannot change — create a new version for updates.<br><strong>One at a time.</strong></p> |
| Rejected         | Review failed with comments; edit and resubmit.                                                | Not publishable until issues are fixed and resubmitted; not visible to users.                                       |
| Canceled         | Author or admin canceled the submission; no further actions except duplicating to a new draft. | Cannot be edited or published; duplicate to restart.                                                                |

Allowed actions by state (high‑level):

* Draft → Submit for publish (moves to Pending approval) or Cancel.
* Pending approval ↔ In review: handled by Marketplace.
* In review → Approved or Rejected.
* Approved → Publish.
* Published → Create new version for further changes.
* Rejected → Edit (back to Draft) → resubmit.
* Canceled → Duplicate to new Draft if needed.

## Typical workflow

Basic workflow diagram:

{% @mermaid/diagram content="graph TD
D\[Draft] -->|Submit publish| P\[Pending approval]
P --> R\[In review]
R -->|Approve| A\[Approved]
R -->|Reject| X\[Rejected]
A -->|Publish| U\[Published]
X -->|Edit & resubmit| D
D -->|Cancel| C\[Canceled]
P -->|Cancel| C
R -->|Cancel| C
C -->|Duplicate| D" %}

1. Create a new version.
2. Fill in version tag, update notes, configure scopes, and select members.
3. Save as draft to validate the information.
4. Submit publish. The version transitions to pending approval and then In review.
5. Store admin reviews scopes, permissions, and release notes.
   * If Approved: you or the admin can proceed to Publish.
   * If Rejected: review feedback, update the draft, and submit again.
6. Once published, the version becomes immutable; create a new version for any further change.

## Scopes and permissions

* Scopes define the range of tenant data your app can access. Request the minimum set necessary (“least privilege”).
* Increasing scope sensitivity (e.g., adding read/write to new data domains) generally requires review and may justify a MINOR or MAJOR version bump.
* If you change scopes on a non‑published version, the state may return to draft and require re‑submission.
* Published versions cannot have their scopes changed. Create a new version instead.

## Availability and members

* Use the members section to specify who can access the version while it is not public (internal QA, stakeholders, or specific tenants).
* Members are captured as part of the version snapshot. Updating members on a draft is allowed; after submission, changes may require re‑submission depending on policy.

## Release notes guidelines

Write concise, user‑readable notes that explain what changed and why. Keep sensitive details out of public notes. Recommended structure:

* Summary in one sentence
* Key changes (bulleted)
* Impact on users/admins
* Any required actions

Example:

* First release of the integration.
* Syncs email contacts and email messages (read‑only).
* No configuration changes required for existing users.

## Good versioning practices

* Bump MAJOR when making breaking changes or requiring new mandatory scopes.
* Bump MINOR when adding new capabilities that are backward compatible.
* Bump PATCH for fixes and internal improvements.
* Always keep release notes in english and under the character limit shown in the UI.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://oten.gitbook.io/identity-support/user-guide/oten-workspace/applications/oten-developer/app-versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.