App versioning
This page describes how to create and manage app versions that are submitted to the Marketplace for review and publication.
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:
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.
Immutable; scopes/notes cannot change — create a new version for updates. One at a time.
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:
Unexpected error with integration mermaid: Integration is not installed on this space
Create a new version.
Fill in version tag, update notes, configure scopes, and select members.
Save as draft to validate the information.
Submit publish. The version transitions to pending approval and then In review.
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.
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.
Last updated