Revise version language #5434
Revise version language #5434
Conversation
|
/gcbrun |
|
Visit the preview URL for this PR (updated for commit b6d586a): |
There was a problem hiding this comment.
Thanks for doing this, I agree the version string format descriptions should just be coupled with the channel descriptions.
Probably out of scope, but would each of these sections be a good place to include a quick:
To switch to /whatever/ channel, run:
dart channel /whatever/
? Idk if it actually works like that though (@johnpryan or DRE on rotation?)
src/get-dart/index.md
Outdated
| Versioning for releases in stable channel of the Dart SDK follows a `x.y.z` format. | ||
| The version strings resemble `1.24.3` and `2.1.0`. | ||
| This format consists of three dot-separated integers without hyphens or letters. | ||
| The versions include the major version (`x`), | ||
| then the minor version (`y`), and then the patch version (`z`). |
There was a problem hiding this comment.
| Versioning for releases in stable channel of the Dart SDK follows a `x.y.z` format. | |
| The version strings resemble `1.24.3` and `2.1.0`. | |
| This format consists of three dot-separated integers without hyphens or letters. | |
| The versions include the major version (`x`), | |
| then the minor version (`y`), and then the patch version (`z`). | |
| **Stable** channel release version strings follow a `x.y.z` format. | |
| The format is three dot-separated integers, without hyphens or letters, | |
| where `x` is the major version, `y` is the minor version, and `z` is the patch version. | |
| For example, `1.24.3` or `2.1.0`. |
I feel like there's a mix of improving the copy in this paragraph, but also introducing wordiness where it was previously more concise. My suggestion is an alternative, but I think the original lines 99-102 was the tightest way to ph Please let me know if you had specific reasoning for elaborating/elongating parts of this that I'm not aware of!
src/get-dart/index.md
Outdated
| These beta channel releases preview features intended for the stable channel. | ||
| Use releases in the beta channel to test new features or | ||
| test compatibility with future releases. | ||
| Don’t use beta releases for production environments. |
There was a problem hiding this comment.
| These beta channel releases preview features intended for the stable channel. | |
| Use releases in the beta channel to test new features or | |
| test compatibility with future releases. | |
| Don’t use beta releases for production environments. | |
| Use beta channel releases to preview and test features in the upcoming stable release. | |
| Don’t use beta releases for production environments. |
To make it more parallel with the stable sections "Use..." statement (maybe too much simplifying though, adjust as needed)
src/get-dart/index.md
Outdated
| Versioning for releases in the **beta** channel of the Dart SDK | ||
| follows the `x.y.z-a.b.beta` format. | ||
| Version strings resemble `2.8.0-20.11.beta`. | ||
| The part before the hyphen follows the stable version format. | ||
| The part after the hyphen adds the pre-release version (`a`), | ||
| then the pre-release patch version (`b`), and then the channel (`beta`). |
There was a problem hiding this comment.
| Versioning for releases in the **beta** channel of the Dart SDK | |
| follows the `x.y.z-a.b.beta` format. | |
| Version strings resemble `2.8.0-20.11.beta`. | |
| The part before the hyphen follows the stable version format. | |
| The part after the hyphen adds the pre-release version (`a`), | |
| then the pre-release patch version (`b`), and then the channel (`beta`). | |
| **Beta** channel release version strings follow a `x.y.z-a.b.beta` format. | |
| The part before the hyphen follows the [stable version format](#stable-channel). | |
| The part after the hyphen adds the pre-release version (`a`), | |
| then the pre-release patch version (`b`), and then the channel (`beta`). | |
| For example, `2.8.0-20.11.beta`. |
Similar to the stable section edit. Here, I only felt like the first sentence could be more concise and mostly changed just to match the stable section suggestion, so take it or leave it!
src/get-dart/index.md
Outdated
| hyphen follows the stable version scheme, `a` and `b` after the hyphen are the | ||
| prerelease and prerelease patch versions, and `beta` or `dev` is the channel. | ||
| ### Stable channel | ||
| Dart deploys a release to the _stable_ channel about every three months. |
There was a problem hiding this comment.
What's the difference between "deploys" used in this section and "releases" used in the other two? Should we just pick one and use it or is there a semantic implication based of the channel type?
There was a problem hiding this comment.
I would say something like "Dart publishes a new release to the stable channel about every three months". These are usually considered minor releases, major releases happen less often.
src/get-dart/index.md
Outdated
| Dart releases a build to the **dev** channel about twice a week. | ||
| The current dev version is `[calculating]`{:.build-rev-dev}. | ||
|
|
||
| These dev channel builds include the most recent codebase with latest changes. |
There was a problem hiding this comment.
| These dev channel builds include the most recent codebase with latest changes. | |
| Use dev channel builds for the most recent changes to the codebase. |
Parallel language with other sections.
Similar question to the "deploys" vs. "releases" question: what's the difference between calling them "dev channel builds" vs "stable/beta channel releases"? Should we pick one and use it consistently?
There was a problem hiding this comment.
question: Good question. Are we "releasing a build" or "deploying a release"? Probably the former, right?
src/get-dart/index.md
Outdated
| Versioning for releases in the **dev** channel of the Dart SDK | ||
| follows the `x.y.z-a.b.dev` format. | ||
| Version strings resemble `2.8.0-20.11.dev`. |
There was a problem hiding this comment.
| Versioning for releases in the **dev** channel of the Dart SDK | |
| follows the `x.y.z-a.b.dev` format. | |
| Version strings resemble `2.8.0-20.11.dev`. | |
| **Dev** channel release version strings follow a `x.y.z-a.b.dev` format, | |
| similar to the [beta version format](#beta-channel). | |
| For example, `2.8.0-20.11.dev`. |
I'm not really married to the way I've rewritten each of these first sentences for each section, but I'm just making the point that they:
- should all be parallel, and
- use a lot of prepositions where all the descriptors can be stacked (imo, idk if that's actually "good grammar" or not)
e.g. "Versioning for releases in the dev channel of the Dart SDK..." can just be "Dev channel release versions..."
src/get-dart/index.md
Outdated
|
|
||
| Use stable channel releases for production environments. | ||
|
|
||
| Versioning for releases in stable channel of the Dart SDK follows a `x.y.z` format. |
There was a problem hiding this comment.
This paragraph is already covered elsewhere: https://dart.dev/tools/pub/versioning#semantic-versions
|
/gcbrun |
|
Moved this change to #5497. Closing. |
Fixes #4414