Governance Overview
SGEN changes according to documented rules. Operators know what to expect when a release ships, what protection exists for features they depend on, and how far in advance breaking changes are announced. This page is the reference for those rules.
What is this for?
Platform governance covers the policies that regulate how SGEN changes over time. It defines what constitutes a breaking change, how far in advance breaking changes are communicated, the deprecation process for features being retired, how the documentation tracks platform versions, and the distinction between announced releases and silent updates.
Read this page when a release communication refers to a governance policy and you need the definition. Read this page when you need to understand how much notice SGEN gives before removing or changing a feature you depend on. Read this page when you are building an integration or workflow against SGEN and need to understand the stability contract.
Scope
This page covers:
- The release gate model — what gates a change before it ships.
- The definition of a breaking change and the policy for handling one.
- The deprecation timeline for features being retired.
- How documentation versions alongside the platform.
- When release announcements ship vs when updates ship silently.
This page does not cover:
- The specific content of any given release — see What's New or Changelog.
- Per-feature stability status — see the feature's Reference page.
- Infrastructure uptime or incident response — those are covered in the Status page.
- Internal engineering process — that is internal documentation, not customer-facing governance.
Vocabulary
| Term | Definition |
|---|---|
| Release | A set of changes shipped to all SGEN instances at the same time |
| Breaking change | A change that removes, renames, or alters a feature in a way that requires operators to take action before the change ships |
| Non-breaking change | An addition or fix that requires no operator action |
| Deprecation | The formal announcement that a feature will be removed in a future release, with a specified timeline |
| Silent update | A non-breaking improvement that ships without a What's New entry |
| Announced release | A release with a corresponding What's New or Changelog entry |
| Documentation version | The documentation state at the time of a given platform release |
Release Gates
SGEN changes must clear four gates before shipping.
| Gate | What it checks | Who operates it |
|---|---|---|
| G1 — Functional verification | The change does what it is designed to do under normal and edge-case conditions | QA pipeline |
| G2 — Regression check | The change does not break any existing behavior in other areas | QA pipeline |
| G3 — Documentation ready | Reference and Guide pages for the changed area are updated and reviewed | Documentation team |
| G4 — Communication ready | Breaking changes have a notice; non-breaking changes have a Changelog entry | Documentation team |
G1 and G2 are always required. G3 is required for features that appear in the customer-facing documentation. G4 is required for all releases. A release that clears G1 and G2 but has not cleared G3 can ship if the changed area has no existing documentation page — the Documentation team logs a doc-debt entry and ships the doc within two releases.
Breaking Change Policy
A breaking change is any change that requires an operator to take deliberate action to preserve the behavior they currently depend on. Breaking changes are not shipped without notice.
Examples of breaking changes:
- A field is renamed — existing integrations or workflows referencing the old name stop working.
- A behavior is reversed — an action that previously returned one result now returns a different result.
- A feature is removed — operators using that feature must move to an alternative.
- A URL pattern changes — existing links or integrations pointing to the old URL stop working.
Examples of non-breaking changes:
- A new field is added to a form — existing forms still work.
- A new module is added to SG-Modules — existing modules are unaffected.
- A display default is changed — operators who have customized the setting are unaffected.
- A performance improvement ships — no behavior changes.
Notice period for breaking changes: Breaking changes ship with a minimum of one full release cycle of notice. The notice appears in the What's New section. The notice includes: what is changing, why it is changing, when it takes effect, and what operators need to do before it ships. Operators who take the required action before the effective date experience no disruption.
Deprecation Timelines
When a feature is scheduled for removal, SGEN follows a deprecation process with a fixed timeline.
Deprecation phase 1 — Announcement. The feature is marked as deprecated in its Reference page and in a What's New entry. The announcement includes: the feature being deprecated, the reason, the replacement (if one exists), and the removal target date. Operators have a minimum of two release cycles from the announcement to the removal date.
Deprecation phase 2 — Sunset window. The deprecated feature continues to function during the sunset window. No new features are built against it. Documentation for the deprecated feature is updated to reflect its deprecated status and to point to the replacement.
Deprecation phase 3 — Removal. At the announced removal date, the feature is removed. A What's New entry marks the removal. The Reference page for the deprecated feature is archived and replaced with a redirect to the replacement feature's Reference page.
| Phase | Duration | Feature state | Documentation state |
|---|---|---|---|
| Announcement | Day 0 | Deprecated, still functions | Marked deprecated, replacement linked |
| Sunset window | Minimum 2 release cycles | Functions, no new development | Updated to guide migration |
| Removal | At announced date | Removed | Archived, redirect installed |
Documentation Versioning
SGEN documentation versions alongside the platform. The documentation at docs.sgen.com always describes the current released version of the platform. It does not describe features that have not shipped.
When a release ships:
- Reference pages for changed areas are updated before the release ships (G3).
- What's New and Changelog entries publish alongside the release.
- Deprecated features have their Reference pages updated to reflect their deprecation status.
- Removed features have their Reference pages archived.
Versioned documentation access: The current docs.sgen.com always serves the current platform version. Previous platform version documentation is available in the Changelog — each Changelog entry links back to the documentation state at the time of that release.
Documentation lag: Occasionally, a non-breaking change ships before its Reference page is updated. When this happens, the Changelog entry for that change includes a note that documentation is pending. The doc-debt entry resolves within two releases.
Announced Releases vs Silent Updates
Not every change ships with a public announcement.
| Update type | Announced? | Where | Criteria |
|---|---|---|---|
| New feature | Yes | What's New | Any net-new capability |
| Feature improvement | Yes | Changelog | Changes existing behavior |
| Breaking change notice | Yes | What's New | Always — see Breaking Change Policy |
| Bug fix | Yes | Changelog | Visible behavior change |
| Performance improvement | Sometimes | Changelog | Only if measurable and customer-visible |
| Infrastructure update | Rarely | Status page | Only if it causes observable behavior change |
| Internal tooling | No | Not published | No customer-visible surface change |
The threshold for a What's New entry is "an operator would want to know this exists." The threshold for a Changelog-only entry is "an operator might encounter this change." The threshold for a silent update is "an operator would not notice a difference."
Examples
Example 1 — An operator evaluating whether a workflow is stable
An operator has built a series of internal content SOPs that depend on the Blog module's scheduling behavior. They read this page to understand the breaking change policy. They learn that any change to Blog scheduling behavior that breaks their workflow must ship with a minimum one release cycle of notice. They know they have time to adapt before any breaking change takes effect. They continue building with confidence.
Example 2 — Reading a deprecation notice
A What's New entry announces that the "Legacy Redirect Manager" feature is deprecated. The operator reads the deprecation notice, follows the link to the "Managed Redirects" replacement feature, and reads the migration guide. Using the timeline on this page, they calculate they have a minimum of two release cycles to complete the migration. They schedule the migration in their next sprint.
Example 3 — Understanding why a Reference page changed
An operator notices that a Reference page for a feature they use shows different field defaults than they remember. They check the Changelog for that area and find a non-breaking change entry noting that the default value for a field changed. Because the change was non-breaking (their existing configuration is unaffected), they were not required to take action. The governance model explains why they received no breaking-change notice — their use case was unaffected.
Edge cases
A breaking change that affects only a subset of operators. SGEN still follows the full breaking change policy for subset-scoped changes. Even if only 10% of operators are affected, the minimum notice period and What's New announcement apply. The announcement may describe the affected conditions clearly ("This change affects operators using the Legacy API integration"). Operators outside the affected condition receive the announcement but need take no action.
A feature removed for security reasons. Security-motivated removals follow an expedited timeline. The standard two-release-cycle notice period may be shortened. Security removals always include an explanation and a replacement or mitigation path. Where immediate removal is necessary, the What's New entry ships at the same time as the removal.
Documentation lags the platform after a fast-moving release. When documentation lag occurs, the Changelog entry for the release notes the pending doc state. The Reference page includes a notice at the top identifying which sections are under update. The notice resolves within two releases.
Where to find it
This page is part of the Shared Concepts Reference section at docs.sgen.com. Navigate to Reference → Shared Concepts → Governance Overview.
Release announcements appear in What's New on docs.sgen.com. Changelog entries for all releases appear in Changelog on docs.sgen.com.
Related features
- Platform Values — the design decisions that explain why the governance model is structured the way it is.
- Shared Concepts Overview — the cross-platform vocabulary the governance model assumes.
- 4-Pillar Diagram — the pillar structure that determines which team owns governance decisions for a given feature.
- How to Read Reference Docs — how Reference pages are updated during a release cycle.