Versioning and stability guarantees #1880

codebien · 2025-02-27T12:11:48Z

What?

It introduces a new page for documenting k6 versioning and stability guarantees. Note, this is expected to be merged only after k6 v1.0.0 release.

Checklist

I have used a meaningful title for the PR.
I have described the changes I've made in the "What?" section above.
I have performed a self-review of my changes.
I have run the npm start command locally and verified that the changes look good.

I have made my changes in the docs/sources/k6/next folder of the documentation.

Related PR(s)/Issue(s)

Related to #1836.

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

codebien · 2025-02-27T12:16:00Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+
+This includes the [go.k6.io/k6/js/modules](https://pkg.go.dev/go.k6.io/[email protected]/js/modules) Go package that internal and external developers have available to build module extensions, as well as the [go.k6.io/k6/output](https://pkg.go.dev/go.k6.io/[email protected]/output) that can be used to build custom outputs for k6.
+
+It also includes public k6 Go packages that are exposed to developers to facilitate the development of these extensions (e.g., the current  [go.k6.io/k6/lib.State](https://pkg.go.dev/go.k6.io/[email protected]/lib#State) package).


I feel this is not clear enough. Any suggestion how to improve? We have defined the policy as an allowlist, should we have here the full list of the supported packages?

Not specific to this sentence, but as I gave the document a read I wondered if we should maybe state at the beggining something along the lines of "anything that is not explicitly covered by this document is not considered stable or supported". Which, I think was pretty much the general approach we had as we wrote it. What do you think?

For this specific case though, now that we have moved internal code in the internal package, would it be good enough to say that "anything that's not in the internal package" is considered public, stable, covered by this policy, and can be used by extensions in respect to k6's versioning scheme"?

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

heitortsergent

Left a few nits and style guide suggestions, overall I think the document looks great. 🙇

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

Co-authored-by: Heitor Tashiro Sergent <[email protected]> Apply suggestions from code review Co-authored-by: Heitor Tashiro Sergent <[email protected]>

codebien · 2025-03-11T15:22:14Z

@heitortsergent @oleiade I've added an admonition at the very beginning as suggested here #1880 (comment)

What do you think?

oleiade · 2025-03-14T10:18:59Z

@codebien Love it 👏🏻

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

Co-authored-by: Daniel González Lopes <[email protected]>

mstoykov

LGTM in general to me!

Given how many times this has happened in the last few years, I would really want there to be a note that we are not responsible for other projects that we depend on breaking their APIs.

Eve832

hey folks, I volunteered to jump in and do a copyedit of this doc for Heitor. I added some suggestions, but wanted express some general comments. I'm not going to block the merge with my review, so take or leave what you'd like :)

The headings get really really nested (H5s don't render well at all) and there are a lot of instances where the doc jumps heading levels, for example, Versioning Strategy is an H2, but the next headings are H4s until you get to Breaking Changes which is an H3? not sure why they don't just make Breaking Changes an H2 and the others H3s
The language is kind of strange throughout the document when we talk about our internal requirements. When we use words like "must," it seems directed at the user, like they need to do the things, when it's actually we that must do the things. This makes the doc seem like an internal one, rather than one meant to inform users. I added an inline comment with an example of how to remedy this.
NIT: we can be kind of wordy at times; for ex. for Major versions we should just simply state that they plan one major release per year, and describe the scope of the changes one would expect. For Minor versions what would add value is again, what a user would expect, like "bug fixes, minor quality of life improvements, etc..."

Eve832 · 2025-03-18T13:09:40Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+1. Removal
+2. Update


Suggested change

1. Removal

2. Update

* Removal

* Update

Eve832 · 2025-03-18T13:10:54Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+1. Deprecate a current API or a feature by following the dedicated policy.
+2. If necessary, add an alternative solution. Ideally, this would be an experimental version within a minor release within the current maintained state. Alternatively, it might be available in a Preview release.
+3. Provide documentation for the migration path.
+4. Proceed with removing the API and releasing a new major version.


Suggested change

1. Deprecate a current API or a feature by following the dedicated policy.

2. If necessary, add an alternative solution. Ideally, this would be an experimental version within a minor release within the current maintained state. Alternatively, it might be available in a Preview release.

3. Provide documentation for the migration path.

4. Proceed with removing the API and releasing a new major version.

1. Deprecate a current API or a feature by following the dedicated policy.

1. If necessary, add an alternative solution. Ideally, this would be an experimental version within a minor release within the current maintained state. Alternatively, it might be available in a Preview release.

1. Provide documentation for the migration path.

1. Proceed with removing the API and releasing a new major version.

I'm not sure if this is intentional, but the way this document is worded makes it sound like we're expecting users to do these things, not that they're a promise from us to the users.

This can be remedied with language like simply adding something like (for this section), " When we remove an API or feature, we will:"

Eve832 · 2025-03-18T13:13:55Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+1. Apply the changes, then publish them in the next major version. If the change is significant, it might be convenient to make it available in a Preview release that can support the migration path until a version is globally available.
+2. Provide documentation for the migration path.


Suggested change

1. Apply the changes, then publish them in the next major version. If the change is significant, it might be convenient to make it available in a Preview release that can support the migration path until a version is globally available.

2. Provide documentation for the migration path.

1. Apply the changes, then publish them in the next major version. If the change is significant, it might be convenient to make it available in a Preview release that can support the migration path until a version is globally available.

1. Provide documentation for the migration path.

Eve832 · 2025-03-18T13:14:27Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+1. Release notes and CHANGELOGs.
+2. Official documentation.
+3. When the user directly interacts with the feature.
+4. An alternative already available is recommended, but it shouldn’t be considered mandatory.


Suggested change

1. Release notes and CHANGELOGs.

2. Official documentation.

3. When the user directly interacts with the feature.

4. An alternative already available is recommended, but it shouldn’t be considered mandatory.

1. Release notes and CHANGELOGs.

1. Official documentation.

1. When the user directly interacts with the feature.

1. An alternative already available is recommended, but it shouldn’t be considered mandatory.

Eve832 · 2025-03-18T13:15:15Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+
+### Migration
+
+When a breaking change is introduced, or an API is superseded, then documentation for a migration guide must be provided to users to help them understand how to move from version to version.


another example of strange internal type language... I'd replace words like "must" with words like "will" or "are"

Eve832 · 2025-03-18T13:16:04Z

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md

+1. _We don't backport features_ from one major version to any previous ones.
+2. We only provide changes on the latest release of each support category: _at any point in time, there are single officially under-development and actively maintained versions_. We do not support multiple versions of each support path. For example, suppose a bug is found in v1.1.0, and the latest v1.Y.Z published release is v1.3.2. In that case, if and only if the latest release is affected, and the bug or security issue is deemed important enough, only then does the development team define as a priority to publish a fix that will be released in v1.3.3. Users cannot expect a v1.1.1 fix release.
+3. Our products, services, and teams building upon k6 are expected to develop their versioning integration built on our support policies.


Suggested change

1. _We don't backport features_ from one major version to any previous ones.

2. We only provide changes on the latest release of each support category: _at any point in time, there are single officially under-development and actively maintained versions_. We do not support multiple versions of each support path. For example, suppose a bug is found in v1.1.0, and the latest v1.Y.Z published release is v1.3.2. In that case, if and only if the latest release is affected, and the bug or security issue is deemed important enough, only then does the development team define as a priority to publish a fix that will be released in v1.3.3. Users cannot expect a v1.1.1 fix release.

3. Our products, services, and teams building upon k6 are expected to develop their versioning integration built on our support policies.

1. _We don't backport features_ from one major version to any previous ones.

1. We only provide changes on the latest release of each support category: _at any point in time, there are single officially under-development and actively maintained versions_. We do not support multiple versions of each support path. For example, suppose a bug is found in v1.1.0, and the latest v1.Y.Z published release is v1.3.2. In that case, if and only if the latest release is affected, and the bug or security issue is deemed important enough, only then does the development team define as a priority to publish a fix that will be released in v1.3.3. Users cannot expect a v1.1.1 fix release.

1. Our products, services, and teams building upon k6 are expected to develop their versioning integration built on our support policies.

codebien self-assigned this Feb 27, 2025

codebien marked this pull request as ready for review February 27, 2025 12:12

codebien requested review from heitortsergent and a team as code owners February 27, 2025 12:12

codebien requested review from mstoykov and inancgumus and removed request for a team February 27, 2025 12:12

codebien commented Feb 27, 2025

View reviewed changes

codebien requested review from oleiade, olegbespalov, joanlopez, andrewslotin, dgzlopes and pablochacin February 27, 2025 12:16

pablochacin reviewed Feb 27, 2025

View reviewed changes

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md Outdated Show resolved Hide resolved

olegbespalov removed their request for review March 10, 2025 09:35

heitortsergent reviewed Mar 11, 2025

View reviewed changes

codebien and others added 4 commits March 11, 2025 15:16

Added a new page for versioning and stability guarantees

d29b744

Apply @heitortsergent's suggestions

4f717da

Co-authored-by: Heitor Tashiro Sergent <[email protected]> Apply suggestions from code review Co-authored-by: Heitor Tashiro Sergent <[email protected]>

Refined few conditions

e2b215b

Added allow list admonition

1816770

codebien force-pushed the support-policy branch from fc0de19 to 1816770 Compare March 11, 2025 15:05

Link k6 repo

b2ae565

codebien requested a review from heitortsergent March 11, 2025 15:22

dgzlopes reviewed Mar 14, 2025

View reviewed changes

docs/sources/k6/next/misc/versioning-and-stability-guarantees.md Outdated Show resolved Hide resolved

Fixed a typo

53c11fe

Co-authored-by: Daniel González Lopes <[email protected]>

mstoykov reviewed Mar 17, 2025

View reviewed changes

Eve832 reviewed Mar 18, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Versioning and stability guarantees #1880

Versioning and stability guarantees #1880

codebien commented Feb 27, 2025 •

edited by heitortsergent

Loading

codebien Feb 27, 2025

oleiade Mar 5, 2025

heitortsergent left a comment

codebien commented Mar 11, 2025

oleiade commented Mar 14, 2025

mstoykov left a comment

Eve832 left a comment

Eve832 Mar 18, 2025

Eve832 Mar 18, 2025

Eve832 Mar 18, 2025

Eve832 Mar 18, 2025

Eve832 Mar 18, 2025

Eve832 Mar 18, 2025

Eve832 Mar 18, 2025


		This includes the [go.k6.io/k6/js/modules](https://pkg.go.dev/go.k6.io/[email protected]/js/modules) Go package that internal and external developers have available to build module extensions, as well as the [go.k6.io/k6/output](https://pkg.go.dev/go.k6.io/[email protected]/output) that can be used to build custom outputs for k6.

		It also includes public k6 Go packages that are exposed to developers to facilitate the development of these extensions (e.g., the current [go.k6.io/k6/lib.State](https://pkg.go.dev/go.k6.io/[email protected]/lib#State) package).

		1. Apply the changes, then publish them in the next major version. If the change is significant, it might be convenient to make it available in a Preview release that can support the migration path until a version is globally available.
		2. Provide documentation for the migration path.


		### Migration

		When a breaking change is introduced, or an API is superseded, then documentation for a migration guide must be provided to users to help them understand how to move from version to version.

Versioning and stability guarantees #1880

Are you sure you want to change the base?

Versioning and stability guarantees #1880

Conversation

codebien commented Feb 27, 2025 • edited by heitortsergent Loading

What?

Checklist

Related PR(s)/Issue(s)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heitortsergent left a comment

Choose a reason for hiding this comment

codebien commented Mar 11, 2025

oleiade commented Mar 14, 2025

mstoykov left a comment

Choose a reason for hiding this comment

Eve832 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codebien commented Feb 27, 2025 •

edited by heitortsergent

Loading