mirror of
https://github.com/Myriad-Dreamin/tinymist.git
synced 2025-08-04 18:28:02 +00:00
docs: update release instruction (#1163)
This commit is contained in:
Myriad-Dreamin
GitHub
parent
4ab9680078
commit
a33f12ea7b
10 changed files with 220 additions and 4 deletions
30
docs/assets/images/release-instruction.typ-inlined0.svg
Normal file
30
docs/assets/images/release-instruction.typ-inlined0.svg
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
<svg class="typst-doc" viewBox="0 0 30.168111111111113 17.413" width="30.168111111111113pt" height="17.413pt" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:h5="http://www.w3.org/1999/xhtml">
|
||||
<g>
|
||||
<g transform="translate(0 12.463)">
|
||||
<g class="typst-text" transform="scale(1, -1)">
|
||||
<use xlink:href="#g7AEDD6629976B0AE3C2A563E8B08CB8A" x="0" fill="#c0caf5" fill-rule="nonzero"/>
|
||||
</g>
|
||||
</g>
|
||||
<g transform="translate(13.054555555555556 12.463)">
|
||||
<g class="typst-text" transform="scale(1, -1)">
|
||||
<use xlink:href="#gC7144C9284481AC4338A8D8EBEED61FF" x="0" fill="#c0caf5" fill-rule="nonzero"/>
|
||||
</g>
|
||||
</g>
|
||||
<g transform="translate(24.668111111111113 12.463)">
|
||||
<g class="typst-text" transform="scale(1, -1)">
|
||||
<use xlink:href="#g6D82919B92CC880D76DB5835CFD56162" x="0" fill="#c0caf5" fill-rule="nonzero"/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
<defs id="glyph">
|
||||
<symbol id="g7AEDD6629976B0AE3C2A563E8B08CB8A" overflow="visible">
|
||||
<path d="M 9.504 7.513 C 9.295 7.513 8.613 7.48 8.404 7.48 C 8.195 7.48 7.502 7.513 7.2929997 7.513 C 7.128 7.513 7.051 7.425 7.051 7.249 C 7.051 7.15 7.128 7.095 7.2929997 7.084 C 7.755 7.084 7.986 6.941 7.986 6.6549997 C 7.986 6.5889997 7.975 6.512 7.9639997 6.435 L 6.776 1.727 L 4.411 7.282 C 4.323 7.491 4.301 7.513 4.026 7.513 L 2.563 7.513 C 2.299 7.513 2.2 7.491 2.2 7.249 C 2.2 7.139 2.321 7.084 2.552 7.084 C 3.014 7.084 3.245 7.073 3.256 7.04 L 1.793 1.21 C 1.694 0.781 1.441 0.539 1.045 0.462 C 0.759 0.429 0.429 0.473 0.429 0.16499999 C 0.429 0.055 0.495 0 0.616 0 C 0.814 0 1.496 0.033 1.705 0.033 C 1.914 0.033 2.618 0 2.827 0 C 2.992 0 3.069 0.088 3.069 0.264 C 3.069 0.363 2.981 0.41799998 2.805 0.429 C 2.354 0.44 2.134 0.583 2.134 0.858 C 2.134 0.913 2.145 0.99 2.167 1.1 L 3.586 6.721 L 6.336 0.231 C 6.402 0.077 6.49 0 6.5889997 0 C 6.6879997 0 6.754 0.088 6.798 0.264 L 8.327 6.314 C 8.47 6.875 8.778 7.073 9.46 7.084 C 9.614 7.095 9.691 7.183 9.691 7.3589997 C 9.658 7.458 9.647 7.513 9.504 7.513 Z "/>
|
||||
</symbol>
|
||||
<symbol id="gC7144C9284481AC4338A8D8EBEED61FF" overflow="visible">
|
||||
<path d="M 7.546 2.497 C 7.656 2.552 7.711 2.629 7.711 2.75 C 7.711 2.871 7.656 2.948 7.546 3.003 L 1.232 5.995 C 1.199 6.006 1.155 6.017 1.111 6.017 C 0.935 6.017 0.847 5.929 0.847 5.742 C 0.847 5.643 0.902 5.566 1.001 5.522 L 6.875 2.75 L 1.001 -0.022 C 0.902 -0.066 0.847 -0.143 0.847 -0.242 C 0.847 -0.429 0.935 -0.517 1.111 -0.517 C 1.155 -0.517 1.199 -0.506 1.232 -0.495 Z "/>
|
||||
</symbol>
|
||||
<symbol id="g6D82919B92CC880D76DB5835CFD56162" overflow="visible">
|
||||
<path d="M 2.739 -0.242 C 4.29 -0.242 5.06 1.012 5.06 3.52 C 5.06 5.203 4.708 6.325 4.015 6.875 C 3.6299999 7.172 3.201 7.3259997 2.75 7.3259997 C 1.199 7.3259997 0.429 6.061 0.429 3.52 C 0.429 1.496 0.968 -0.242 2.739 -0.242 Z M 3.971 5.764 C 4.048 5.379 4.081 4.675 4.081 3.652 C 4.081 2.6399999 4.037 1.892 3.96 1.408 C 3.817 0.528 3.41 0.088 2.739 0.088 C 2.486 0.088 2.233 0.187 2.002 0.374 C 1.705 0.627 1.529 1.144 1.452 1.936 C 1.419 2.211 1.408 2.783 1.408 3.652 C 1.408 4.609 1.441 5.2799997 1.496 5.643 C 1.595 6.248 1.793 6.633 2.101 6.798 C 2.343 6.93 2.552 6.996 2.739 6.996 C 3.454 6.996 3.85 6.413 3.971 5.764 Z "/>
|
||||
</symbol>
|
||||
</defs>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.3 KiB |
30
docs/assets/images/release-instruction.typ-inlined1.svg
Normal file
30
docs/assets/images/release-instruction.typ-inlined1.svg
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
<svg class="typst-doc" viewBox="0 0 30.168111111111113 17.413" width="30.168111111111113pt" height="17.413pt" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:h5="http://www.w3.org/1999/xhtml">
|
||||
<g>
|
||||
<g transform="translate(0 12.463)">
|
||||
<g class="typst-text" transform="scale(1, -1)">
|
||||
<use xlink:href="#g7AEDD6629976B0AE3C2A563E8B08CB8A" x="0" fill="#000000" fill-rule="nonzero"/>
|
||||
</g>
|
||||
</g>
|
||||
<g transform="translate(13.054555555555556 12.463)">
|
||||
<g class="typst-text" transform="scale(1, -1)">
|
||||
<use xlink:href="#gC7144C9284481AC4338A8D8EBEED61FF" x="0" fill="#000000" fill-rule="nonzero"/>
|
||||
</g>
|
||||
</g>
|
||||
<g transform="translate(24.668111111111113 12.463)">
|
||||
<g class="typst-text" transform="scale(1, -1)">
|
||||
<use xlink:href="#g6D82919B92CC880D76DB5835CFD56162" x="0" fill="#000000" fill-rule="nonzero"/>
|
||||
</g>
|
||||
</g>
|
||||
</g>
|
||||
<defs id="glyph">
|
||||
<symbol id="g7AEDD6629976B0AE3C2A563E8B08CB8A" overflow="visible">
|
||||
<path d="M 9.504 7.513 C 9.295 7.513 8.613 7.48 8.404 7.48 C 8.195 7.48 7.502 7.513 7.2929997 7.513 C 7.128 7.513 7.051 7.425 7.051 7.249 C 7.051 7.15 7.128 7.095 7.2929997 7.084 C 7.755 7.084 7.986 6.941 7.986 6.6549997 C 7.986 6.5889997 7.975 6.512 7.9639997 6.435 L 6.776 1.727 L 4.411 7.282 C 4.323 7.491 4.301 7.513 4.026 7.513 L 2.563 7.513 C 2.299 7.513 2.2 7.491 2.2 7.249 C 2.2 7.139 2.321 7.084 2.552 7.084 C 3.014 7.084 3.245 7.073 3.256 7.04 L 1.793 1.21 C 1.694 0.781 1.441 0.539 1.045 0.462 C 0.759 0.429 0.429 0.473 0.429 0.16499999 C 0.429 0.055 0.495 0 0.616 0 C 0.814 0 1.496 0.033 1.705 0.033 C 1.914 0.033 2.618 0 2.827 0 C 2.992 0 3.069 0.088 3.069 0.264 C 3.069 0.363 2.981 0.41799998 2.805 0.429 C 2.354 0.44 2.134 0.583 2.134 0.858 C 2.134 0.913 2.145 0.99 2.167 1.1 L 3.586 6.721 L 6.336 0.231 C 6.402 0.077 6.49 0 6.5889997 0 C 6.6879997 0 6.754 0.088 6.798 0.264 L 8.327 6.314 C 8.47 6.875 8.778 7.073 9.46 7.084 C 9.614 7.095 9.691 7.183 9.691 7.3589997 C 9.658 7.458 9.647 7.513 9.504 7.513 Z "/>
|
||||
</symbol>
|
||||
<symbol id="gC7144C9284481AC4338A8D8EBEED61FF" overflow="visible">
|
||||
<path d="M 7.546 2.497 C 7.656 2.552 7.711 2.629 7.711 2.75 C 7.711 2.871 7.656 2.948 7.546 3.003 L 1.232 5.995 C 1.199 6.006 1.155 6.017 1.111 6.017 C 0.935 6.017 0.847 5.929 0.847 5.742 C 0.847 5.643 0.902 5.566 1.001 5.522 L 6.875 2.75 L 1.001 -0.022 C 0.902 -0.066 0.847 -0.143 0.847 -0.242 C 0.847 -0.429 0.935 -0.517 1.111 -0.517 C 1.155 -0.517 1.199 -0.506 1.232 -0.495 Z "/>
|
||||
</symbol>
|
||||
<symbol id="g6D82919B92CC880D76DB5835CFD56162" overflow="visible">
|
||||
<path d="M 2.739 -0.242 C 4.29 -0.242 5.06 1.012 5.06 3.52 C 5.06 5.203 4.708 6.325 4.015 6.875 C 3.6299999 7.172 3.201 7.3259997 2.75 7.3259997 C 1.199 7.3259997 0.429 6.061 0.429 3.52 C 0.429 1.496 0.968 -0.242 2.739 -0.242 Z M 3.971 5.764 C 4.048 5.379 4.081 4.675 4.081 3.652 C 4.081 2.6399999 4.037 1.892 3.96 1.408 C 3.817 0.528 3.41 0.088 2.739 0.088 C 2.486 0.088 2.233 0.187 2.002 0.374 C 1.705 0.627 1.529 1.144 1.452 1.936 C 1.419 2.211 1.408 2.783 1.408 3.652 C 1.408 4.609 1.441 5.2799997 1.496 5.643 C 1.595 6.248 1.793 6.633 2.101 6.798 C 2.343 6.93 2.552 6.996 2.739 6.996 C 3.454 6.996 3.85 6.413 3.971 5.764 Z "/>
|
||||
</symbol>
|
||||
</defs>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.3 KiB |
|
|
@ -117,3 +117,7 @@ To run e2e tests for tinymist on Windows:
|
|||
./scripts/e2e.ps1
|
||||
```
|
||||
|
||||
## Release on GitHub
|
||||
|
||||
The code owners and maintainers of the release channels can check the [Release Guide](/dev-guide/release-instruction.md) to learn how to check and release the new version of tinymist.
|
||||
|
||||
|
|
|
|||
71
docs/release-instruction.md
Normal file
71
docs/release-instruction.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/release-instruction.typ. Do not edit manually. -->
|
||||
# Release Instructions
|
||||
|
||||
## Updating Version String to Release
|
||||
|
||||
- The `tinymist-assets` package
|
||||
- package.json should be the version.
|
||||
- The VSCode Extension
|
||||
- package.json should be the version.
|
||||
- The Language Server Binaries
|
||||
- Cargo.toml should be the version.
|
||||
- The `tinymist-web` NPM package
|
||||
- package.json should be the version.
|
||||
|
||||
You can `grep` the version number in the repository to check if all the components are updated. Some CI script will also assert failing to help you catch the issue.
|
||||
|
||||
## Updating the Changelog
|
||||
|
||||
All released version must be documented in the changelog. The changelog is located at `editors/vscode/CHANGELOG.md`. Please ensure the correct format otherwise CI will fail.
|
||||
|
||||
## Generating the GitHub Release's Body (Content)
|
||||
|
||||
Run following commands to generate the body of the release announcement:
|
||||
|
||||
```bash
|
||||
$ yarn draft-release 0.12.19
|
||||
Please check the generated announcement in target/announcement.gen.md
|
||||
```
|
||||
|
||||
The `target/announcement.gen.md` first includes the changelog read from the `CHANGELOG.md` file, then attack the download script and available download links.
|
||||
|
||||
## Drafting the Release
|
||||
|
||||
Create a draft release on GitHub with the generated announcement.
|
||||
|
||||
If you are releasing a nightly version, please set the prerelease flag to true. Otherwise, if you are releasing a regular version, please set the prerelease flag to false. Some package registries relies on this flag to determine whether to update their stable channel.
|
||||
|
||||
Tinymist's versions follow the [Semantic Versioning](https://semver.org/) scheme, in format of `MAJOR.MINOR.PATCH`. Besides, tinymist follows special rules for the version number:
|
||||
- If a version is suffixed with `-rcN` (<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/images/release-instruction.typ-inlined0.svg"><img style="vertical-align: -0.35em" alt="typst-block" src="./assets/images/release-instruction.typ-inlined1.svg" /></picture>), e.g. `0.11.0-rc1` and `0.12.1-rc1`, it means this version is a release candidate. It is used to test publish script and E2E functionalities. These versions will not be published to the marketplace.
|
||||
- If the `PATCH` number is odd, e.g. `0.11.1` and `0.12.3`, it means this version is a nightly release. The nightly release will use both [tinymist](https://github.com/Myriad-Dreamin/tinymist/tree/main) and [typst](https://github.com/typst/typst/tree/main) at **main branch**. They will be published as prerelease version to the marketplace.
|
||||
- Otherwise, if the `PATCH` number is even, e.g. `0.11.0` and `0.12.2`, it means this version is a regular release. The regular release will always use the recent stable version of tinymist and typst.
|
||||
|
||||
|
||||
## Checking the `Cargo.toml` and the `Cargo.lock`
|
||||
|
||||
A `git` with `branch` dependency is forbidden in the `Cargo.toml` file. This will cause the `Cargo.lock` file to be unstable and the build to fail. Use the `git` with `tag` dependencies instead.
|
||||
|
||||
## Publishing the tinymist-assets crate
|
||||
|
||||
Ensure that the `tinymist-assets` crate is published to the registry. Please see `Cargo.lock` to check the released crate is used correctly.
|
||||
|
||||
## Dry running the CI
|
||||
|
||||
Dry running the `release.yml` and the `release-vscode.yml` if you feel necessary.
|
||||
|
||||
## Tagging the Release
|
||||
|
||||
Push a tag to the repository with the version number. For example, if you are releasing version `0.12.19`, you should run the following command:
|
||||
|
||||
```bash
|
||||
$ git tag v0.12.19
|
||||
$ git push --tag
|
||||
```
|
||||
|
||||
This step will trigger the `release-vscode.yml` CI to build and publish the VS Code extensions to the marketplace.
|
||||
|
||||
## Triggering the Binary Releases
|
||||
|
||||
The binary releases is triggered by the `release.yml` CI. You should trigger it after `release-vscode.yml` finished.
|
||||
|
||||
The `release.yml` CI will finally undraft the GitHub release automatically that inform everyone the release is ready.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
// dist/tinymist/rs
|
||||
#import "mod.typ": *
|
||||
|
||||
|
|
@ -18,10 +19,7 @@ It contains:
|
|||
|
||||
== Versioning and Release Cycle
|
||||
|
||||
Tinymist's versions follow the #link("https://semver.org/")[Semantic Versioning] scheme, in format of `MAJOR.MINOR.PATCH`. Besides, tinymist follows special rules for the version number:
|
||||
- If a version is suffixed with `-rcN` ($N > 0$), e.g. `0.11.0-rc1` and `0.12.1-rc1`, it means this version is a release candidate. It is used to test publish script and E2E functionalities. These versions will not be published to the marketplace.
|
||||
- If the `PATCH` number is odd, e.g. `0.11.1` and `0.12.3`, it means this version is a nightly release. The nightly release will use both #link("https://github.com/Myriad-Dreamin/tinymist/tree/main")[tinymist] and #link("https://github.com/typst/typst/tree/main")[typst] at *main branch*. They will be published as prerelease version to the marketplace.
|
||||
- Otherwise, if the `PATCH` number is even, e.g. `0.11.0` and `0.12.2`, it means this version is a regular release. The regular release will always use the recent stable version of tinymist and typst.
|
||||
#include "versioning.typ"
|
||||
|
||||
The release cycle is as follows:
|
||||
- If there is a typst version update, a new major or minor version will be released intermediately. This means tinymist will always align the minor version with typst.
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@
|
|||
#import "/docs/tinymist/book.typ": book-page, cross-link
|
||||
#import "/typ/templates/page.typ": *
|
||||
#import "@preview/fletcher:0.4.4" as fletcher: *
|
||||
#import "@preview/numbly:0.1.0": numbly
|
||||
|
||||
/// This function is to render a text string in monospace style and function
|
||||
/// color in your defining themes.
|
||||
|
|
|
|||
70
docs/tinymist/release-instruction.typ
Normal file
70
docs/tinymist/release-instruction.typ
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
#import "mod.typ": *
|
||||
|
||||
#show: book-page.with(title: "Release Instructions")
|
||||
|
||||
#set heading(numbering: numbly(none, "Step {2:1}~"))
|
||||
|
||||
== Updating Version String to Release
|
||||
|
||||
- The `tinymist-assets` package
|
||||
- package.json should be the version.
|
||||
- The VSCode Extension
|
||||
- package.json should be the version.
|
||||
- The Language Server Binaries
|
||||
- Cargo.toml should be the version.
|
||||
- The `tinymist-web` NPM package
|
||||
- package.json should be the version.
|
||||
|
||||
You can `grep` the version number in the repository to check if all the components are updated. Some CI script will also assert failing to help you catch the issue.
|
||||
|
||||
== Updating the Changelog
|
||||
|
||||
All released version must be documented in the changelog. The changelog is located at `editors/vscode/CHANGELOG.md`. Please ensure the correct format otherwise CI will fail.
|
||||
|
||||
== Generating the GitHub Release's Body (Content)
|
||||
|
||||
Run following commands to generate the body of the release announcement:
|
||||
|
||||
```bash
|
||||
$ yarn draft-release 0.12.19
|
||||
Please check the generated announcement in target/announcement.gen.md
|
||||
```
|
||||
|
||||
The `target/announcement.gen.md` first includes the changelog read from the `CHANGELOG.md` file, then attack the download script and available download links.
|
||||
|
||||
== Drafting the Release
|
||||
|
||||
Create a draft release on GitHub with the generated announcement.
|
||||
|
||||
If you are releasing a nightly version, please set the prerelease flag to true. Otherwise, if you are releasing a regular version, please set the prerelease flag to false. Some package registries relies on this flag to determine whether to update their stable channel.
|
||||
|
||||
#include "versioning.typ"
|
||||
|
||||
== Checking the `Cargo.toml` and the `Cargo.lock`
|
||||
|
||||
A `git` with `branch` dependency is forbidden in the `Cargo.toml` file. This will cause the `Cargo.lock` file to be unstable and the build to fail. Use the `git` with `tag` dependencies instead.
|
||||
|
||||
== Publishing the tinymist-assets crate
|
||||
|
||||
Ensure that the `tinymist-assets` crate is published to the registry. Please see `Cargo.lock` to check the released crate is used correctly.
|
||||
|
||||
== Dry running the CI
|
||||
|
||||
Dry running the `release.yml` and the `release-vscode.yml` if you feel necessary.
|
||||
|
||||
== Tagging the Release
|
||||
|
||||
Push a tag to the repository with the version number. For example, if you are releasing version `0.12.19`, you should run the following command:
|
||||
|
||||
```bash
|
||||
$ git tag v0.12.19
|
||||
$ git push --tag
|
||||
```
|
||||
|
||||
This step will trigger the `release-vscode.yml` CI to build and publish the VS Code extensions to the marketplace.
|
||||
|
||||
== Triggering the Binary Releases
|
||||
|
||||
The binary releases is triggered by the `release.yml` CI. You should trigger it after `release-vscode.yml` finished.
|
||||
|
||||
The `release.yml` CI will finally undraft the GitHub release automatically that inform everyone the release is ready.
|
||||
4
docs/tinymist/versioning.typ
Normal file
4
docs/tinymist/versioning.typ
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
Tinymist's versions follow the #link("https://semver.org/")[Semantic Versioning] scheme, in format of `MAJOR.MINOR.PATCH`. Besides, tinymist follows special rules for the version number:
|
||||
- If a version is suffixed with `-rcN` ($N > 0$), e.g. `0.11.0-rc1` and `0.12.1-rc1`, it means this version is a release candidate. It is used to test publish script and E2E functionalities. These versions will not be published to the marketplace.
|
||||
- If the `PATCH` number is odd, e.g. `0.11.1` and `0.12.3`, it means this version is a nightly release. The nightly release will use both #link("https://github.com/Myriad-Dreamin/tinymist/tree/main")[tinymist] and #link("https://github.com/typst/typst/tree/main")[typst] at *main branch*. They will be published as prerelease version to the marketplace.
|
||||
- Otherwise, if the `PATCH` number is even, e.g. `0.11.0` and `0.12.2`, it means this version is a regular release. The regular release will always use the recent stable version of tinymist and typst.
|
||||
Loading…
Add table
Add a link
Reference in a new issue