Skip to content

Latest commit

 

History

History
129 lines (98 loc) · 5.5 KB

SUPPORT.md

File metadata and controls

129 lines (98 loc) · 5.5 KB
Raw

Maintenance & Support Policy

This document describes the Maintenance & Support Policy applicable to releases of the jsii compiler (npm:jsii) with versions 5.0.x and newer.

Versioning Scheme

In-scope jsii release lines use the same major.minor version as the TypeScript compiler (npm:typescript) they are built with. This means that jsii@5.0.x is built on top of typescript@5.0.x.

Since the typescript package does not follow Semantic Versioning, the jsii package does not eiher. The typescript compiler guarantees no breaking change is introduced within a given major.minor release line, and jsii upholds the same guarantee. As a consequence, users are advised to use ~ ranges (also referred to as minor-pinned ranges) when declaring dependencies on jsii.

New jsii release lines will be started matching new typescript compiler releases shortly after they become latest (i.e: the first regular release of is issued).

Release Lines Lifecycle Stages

This Maintenance & Support Policy assigns one of the following lifecycle stages to each in-scope jsii release line in existence:

  1. Current: The latest release line is always the Current one. This is the release under active development, receiving new features, bug fixes and security updates.

  2. Maintenace: Release lines in Maintenance stage are no longer considered in active development, and no new features will be added to these. They however continue to receive bug fixes and security updates. Users can continue to use release lines in Maintenance stage indefinitely, but we recommend they regularly upgrade to the Current release lines in order to keep the necessary effort low.

  3. End-of-Support: Release lines in End-of-Support are considered defunct and are no longer maintained. They no longer receive new features, bug fixes, or security updates. End-of-Support releases may continue to be usable for a period of time, but they could be indirectly broken by changes in newer releases at any time. Users are advised to migrate away from End-of-Support release lines at the earliest convenience.

Stage Transitions

---
title: Release Line Lifecycle
---
stateDiagram-v2
  direction LR

  EoL: End-of-Support

  [*] --> Current
  Current --> Maintenance : new release line started
  Maintenance --> EoL : after 6 months
  EoL --> [*]
Loading

Whenever a new release line is started (typically with a new x.y.0 release, excluding pre-releases), it becomes Current and the release line it replaced immediately enters the Maintenace stage.

Releases stay in the Maintenance stage for a minimum of 6 months before they reach End-of-Support.

Once a release line has reached End-of-Support, it remains in this stage indefinitely.

Timelines & Communication

The typescript compiler maintainers start a new release line on a quarterly basis, and users should expect the jsii compiler maintainers to do the same. Users should expect some small code changes may be necessary when upgrading from one release line to another, as a result of breaking changes introduced by the typescript compiler or jsii itself. In either case, the release notes for the first release in a line includes the relevant information about the breaking changes and instructions for users to fix their codebase.

The jsii compiler has a built-in mechanism to inform users that they are using an unsupported or soon-to-become unsupported release line. A message is emitted to STDERR when invoking the jsii command if the current release is:

  • End-of-Support already
  • Planned to move to End-of-Support within the next 30 calendar days

The built-in messaging can only be expected to deliver the message if the compiler is on the latest available release within the line, or if the environment in which the compiler is run is able to download the lifecycle manifest document.

The current status of jsii compiler release lines is also documented on the repository's README.md document.

Modification

The maintainers of the jsii project reserve the right to modify this Maintenance and Support Policy as necessary. Updates will be proposed by way of a pull request updating this document. Updates that materially affect the support timeline of release lines will be broadly announced to the community via established communication channels (such as the cdk.dev Slack), and will remain open for the community to comment on for a minimum of 15 days.

Community members are welcome to propose changes to the support and maintenace policy through the same process.

Derogation

Under exceptional circumstances, the project maintainers may elect to derogate from this Support & Maintenance Policy. In cases where the decisision to derogate extends supplemental maintenance & support coverage for a release line, the increased coverage will be documented in the repository's README.md document.

However, in situations where the derogation results in reduced support for one or more release lines, the decision to derogate is considered a "break glass" event and maintainers will document the motivation for the derogation, as well as provide the post-mortem analysis to determine and address the reason why this decision has to be taken, including an action plan put in place to ensure the same situation does not occur again in the future.