-
Notifications
You must be signed in to change notification settings - Fork 228
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
base: main
Are you sure you want to change the base?
Conversation
|
||
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). |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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"?
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this 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. 🙇
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Heitor Tashiro Sergent <[email protected]> Apply suggestions from code review Co-authored-by: Heitor Tashiro Sergent <[email protected]>
fc0de19
to
1816770
Compare
@heitortsergent @oleiade I've added an admonition at the very beginning as suggested here #1880 (comment) What do you think? |
@codebien Love it 👏🏻 |
docs/sources/k6/next/misc/versioning-and-stability-guarantees.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Daniel González Lopes <[email protected]>
There was a problem hiding this 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.
There was a problem hiding this 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 :)
- 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..."
1. Removal | ||
2. Update |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
1. Removal | |
2. Update | |
* Removal | |
* Update |
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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:"
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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"
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
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
npm start
command locally and verified that the changes look good.docs/sources/k6/next
folder of the documentation.Related PR(s)/Issue(s)
Related to #1836.