Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Versioning and stability guarantees #1880

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Versioning and stability guarantees #1880

wants to merge 6 commits into from

Conversation

codebien
Copy link
Contributor

@codebien codebien commented Feb 27, 2025

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.

@codebien codebien self-assigned this Feb 27, 2025
@codebien codebien marked this pull request as ready for review February 27, 2025 12:12
@codebien codebien requested review from heitortsergent and a team as code owners February 27, 2025 12:12
@codebien codebien requested review from mstoykov and inancgumus and removed request for a team February 27, 2025 12:12

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).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"?

@olegbespalov olegbespalov removed their request for review March 10, 2025 09:35
Copy link
Collaborator

@heitortsergent heitortsergent left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@codebien
Copy link
Contributor Author

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

What do you think?

allowlist-admonition

@codebien codebien requested a review from heitortsergent March 11, 2025 15:22
@oleiade
Copy link
Member

oleiade commented Mar 14, 2025

@codebien Love it 👏🏻

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

@mstoykov mstoykov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

@Eve832 Eve832 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

  1. 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
  2. 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.
  3. 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..."

Comment on lines +149 to +150
1. Removal
2. Update
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Removal
2. Update
* Removal
* Update

Comment on lines +154 to +157
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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:"

Comment on lines +161 to +162
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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +171 to +174
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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +200 to +202
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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants