mirror of
https://github.com/FunnyWolf/agentic-soc-platform.git
synced 2026-08-22 13:12:56 +02:00
Prepare v0.4.0 release
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
funnywolf
+1
-1
Submodule asf-doc updated: d8ab5ac33d...cd428aebf8
@@ -5,6 +5,6 @@
|
||||
"0.1.1": "0_1_1_Chaos_before_order",
|
||||
"0.2.0": "0_2_0_OCSF_And_BaseModel",
|
||||
"0.3.0": "0_3_0_MCP_And_ClaudeCodePlugin",
|
||||
"0.4.0": "0_4_0_Less_Is_More"
|
||||
"0.4.0": "0_4_0_I_always_have_a_choice"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -4,6 +4,4 @@
|
||||
|
||||
webhook 和 action_index 的文档有些截图和命令需要更改
|
||||
|
||||
ClaudeCode 要补充一些截图
|
||||
|
||||
url过滤,url打开指定记录,url分享等
|
||||
ClaudeCode 要补充一些截图
|
||||
@@ -0,0 +1,202 @@
|
||||
# Release Runbook
|
||||
|
||||
This runbook is the reusable checklist for preparing and publishing ASP releases. For future release requests, read this document first, then follow the flow below.
|
||||
|
||||
## Information the user should provide
|
||||
|
||||
Before changing files or creating a tag, collect these decisions:
|
||||
|
||||
| Item | Required | Notes |
|
||||
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Version | Yes | Example: `0.4.0`. The release workflow expects a pushed tag named `v<version>`, such as `v0.4.0`. |
|
||||
| Release title | Yes | Example: `I always have a choice`. |
|
||||
| Release scope | Yes | Choose whether to only prepare release files, or also push commits and create the release tag. |
|
||||
| Base version/tag | Usually | Default to the latest release tag, but confirm if the release should use another base. |
|
||||
| Release notes source | Yes | Usually derive from commits since the previous release; the user may also provide curated highlights. |
|
||||
| Developer notes raw material | Usually | Ask the user for background, opinions, tradeoffs, complaints, lessons learned, or loose thoughts. The input can be fragmented; organize it into a coherent developer note. |
|
||||
| Documentation language scope | Yes | Default: update Chinese release notes first, then mirror to English. |
|
||||
| Images or attachments | Optional | If release notes need images, use simple names like `img.png`, `img_1.png`, and avoid extra placeholder descriptions unless requested. |
|
||||
| Validation level | Yes | Confirm whether to run only targeted release checks or broader backend/frontend CI checks. Do not run VitePress docs build unless explicitly requested. |
|
||||
| Publish permission | Yes | Confirm before pushing commits, pushing tags, or triggering GitHub Actions release workflows. |
|
||||
|
||||
## Release files and systems
|
||||
|
||||
Check these areas for every release:
|
||||
|
||||
| Area | Path | Purpose |
|
||||
|-----------------------------|--------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
|
||||
| Release workflow | `.github/workflows/release.yml` | Creates the GitHub Release on `v*` tags, resolves release docs URL, builds compose package. |
|
||||
| Docker image workflow | `.github/workflows/docker.yml` | Builds and pushes backend/frontend GHCR images. |
|
||||
| CI workflow | `.github/workflows/ci.yml` | Defines backend, frontend, and compose package validation. |
|
||||
| Release docs mapping | `deploy/release-docs.json` | Maps version numbers such as `0.4.0` to public release doc slugs. |
|
||||
| Compose packaging | `deploy/package-asp-compose.sh` | Builds `asp-compose-<version>.tar.gz`. |
|
||||
| Compose template | `deploy/asp-compose/` | Files included in the downloadable release package. |
|
||||
| Chinese release notes | `asf-doc/docs/zh/release/<slug>/index.md` | Primary release notes source. Draft Chinese first. |
|
||||
| English release notes | `asf-doc/docs/en/release/<slug>/index.md` | English mirror of the Chinese release notes. |
|
||||
| Docs navigation | `asf-doc/docs/.vitepress/config/zh.ts`, `asf-doc/docs/.vitepress/config/en.ts` | Adds or updates the changelog nav item. |
|
||||
| Main docs submodule pointer | `asf-doc` entry in main repo | Must be committed in the main repo after committing inside `asf-doc`. |
|
||||
|
||||
## Naming conventions
|
||||
|
||||
- Git tag: `v<version>`, for example `v0.4.0`.
|
||||
- Version in workflow output and `deploy/release-docs.json`: no `v`, for example `0.4.0`.
|
||||
- Release doc slug: use underscores and keep it stable after publishing, for example `0_4_0_I_always_have_a_choice`.
|
||||
- GitHub Release title: `v<version> - <title>`, for example `v0.4.0 - I always have a choice`.
|
||||
- Compose archive: `asp-compose-<version>.tar.gz`.
|
||||
- GHCR image tags:
|
||||
- `ghcr.io/<owner>/<repo>/asp-backend:<version>`
|
||||
- `ghcr.io/<owner>/<repo>/asp-frontend:<version>`
|
||||
- `latest` is also pushed for non-`dev` versions by the current Docker workflow.
|
||||
|
||||
## Standard release flow
|
||||
|
||||
1. **Inspect current state**
|
||||
- Check main repo status and branch.
|
||||
- Check `asf-doc` status and branch.
|
||||
- Check latest release tags and whether `v<version>` already exists locally or remotely.
|
||||
- Check recent release workflow runs if a release was attempted before.
|
||||
- Identify unrelated dirty files and exclude them from release commits.
|
||||
|
||||
2. **Confirm release decisions**
|
||||
- Ask for missing user-provided information from the table above.
|
||||
- Confirm whether this task should stop after preparation or push the release tag.
|
||||
- Confirm the tag name before creating or pushing it.
|
||||
|
||||
3. **Prepare release notes**
|
||||
- Generate candidate highlights from commits between the previous release tag and the planned release commit.
|
||||
- Ask the user for raw material for **Developer Notes**. This section is not just a change summary; it can include background, motivation, opinions, lessons learned, tradeoffs, and complaints.
|
||||
- Treat the user's Developer Notes input as source material even when it is scattered or informal. Preserve the intent, but rewrite it into a coherent developer voice.
|
||||
- Write Chinese release notes first under `asf-doc/docs/zh/release/<slug>/index.md`.
|
||||
- Create the matching English page under `asf-doc/docs/en/release/<slug>/index.md`.
|
||||
- Keep Chinese and English sections structurally aligned.
|
||||
- Update VitePress changelog navigation in both `zh.ts` and `en.ts`.
|
||||
|
||||
4. **Update release mapping**
|
||||
- Update `deploy/release-docs.json` so the version points to the release doc slug.
|
||||
- Ensure the slug path exists in both Chinese and English docs when both languages are in scope.
|
||||
|
||||
5. **Commit in the correct order**
|
||||
- Commit `asf-doc` changes inside the `asf-doc` repository.
|
||||
- Commit the main repository changes, including:
|
||||
- `deploy/release-docs.json`
|
||||
- the updated `asf-doc` submodule pointer
|
||||
- Do not include unrelated local files.
|
||||
- Include the required `Co-authored-by` trailer when creating commits.
|
||||
|
||||
6. **Validate before tag**
|
||||
- Confirm `deploy/release-docs.json` can resolve the release version to the intended slug.
|
||||
- Confirm release docs and navigation reference the same title and slug.
|
||||
- Run the compose package validation path used by CI when practical.
|
||||
- Do not run VitePress build unless explicitly requested.
|
||||
- Confirm the final release commit is the commit that should receive the tag.
|
||||
|
||||
7. **Publish**
|
||||
- Push the `asf-doc` release notes commit.
|
||||
- Push the main repository release-preparation commit.
|
||||
- Create an annotated tag:
|
||||
|
||||
```bash
|
||||
git tag -a v<version> -m "v<version> - <title>"
|
||||
```
|
||||
|
||||
- Push the tag:
|
||||
|
||||
```bash
|
||||
git push origin v<version>
|
||||
```
|
||||
|
||||
- Monitor the GitHub Actions Release workflow.
|
||||
|
||||
8. **Post-release checks**
|
||||
- Confirm the GitHub Release exists.
|
||||
- Confirm the compose archive is attached.
|
||||
- Confirm backend and frontend images exist in GHCR with the version tag.
|
||||
- Confirm the release body links to the expected release notes URL.
|
||||
- Confirm the public docs site has or will deploy the release page.
|
||||
|
||||
## Release notes structure
|
||||
|
||||
Use this default structure unless the user requests another format:
|
||||
|
||||
```markdown
|
||||
# <version> - <title>
|
||||
|
||||
## New Features
|
||||
|
||||
## Improvements
|
||||
|
||||
## Deployment and Release Engineering
|
||||
|
||||
## Developer Notes
|
||||
```
|
||||
|
||||
### Developer Notes writing rules
|
||||
|
||||
Developer Notes are usually provided by the user. They may be fragmented, informal, or spoken in the order the user remembers things. Convert that material into a readable developer note:
|
||||
|
||||
- Preserve the user's intent, stance, and tone.
|
||||
- Write from a developer/product-builder perspective, not like marketing copy.
|
||||
- Include background and reasoning, not only "what changed".
|
||||
- It is acceptable to include tradeoffs, frustrations, lessons learned, and opinions when the user provides them.
|
||||
- Organize scattered points into a coherent flow with clear paragraphs.
|
||||
- Do not invent personal feelings or motivations that the user did not provide.
|
||||
- If the supplied material is too thin, ask one focused follow-up question before drafting.
|
||||
|
||||
For small patch releases, this can be shortened to:
|
||||
|
||||
```markdown
|
||||
# <version> - <title>
|
||||
|
||||
## Changes
|
||||
|
||||
## Fixes
|
||||
```
|
||||
|
||||
## Validation commands
|
||||
|
||||
Useful checks:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git tag --list --sort=-creatordate
|
||||
git ls-remote --tags origin "v<version>"
|
||||
```
|
||||
|
||||
Release docs mapping check:
|
||||
|
||||
```bash
|
||||
python -c "import json; c=json.load(open('deploy/release-docs.json', encoding='utf-8')); print(c['releases']['<version>'])"
|
||||
```
|
||||
|
||||
Compose package check:
|
||||
|
||||
```bash
|
||||
bash ./deploy/package-asp-compose.sh --version <version> --output-dir dist-release-check
|
||||
test -f dist-release-check/asp-compose-<version>.tar.gz
|
||||
rm -rf dist-release-check/unpacked
|
||||
mkdir -p dist-release-check/unpacked
|
||||
tar -xzf dist-release-check/asp-compose-<version>.tar.gz -C dist-release-check/unpacked
|
||||
```
|
||||
|
||||
Clean up temporary validation output after checking:
|
||||
|
||||
```bash
|
||||
rm -rf dist-release-check
|
||||
```
|
||||
|
||||
## Failure handling
|
||||
|
||||
- If validation fails before the tag is pushed, fix the release-preparation commit before creating the tag.
|
||||
- If the tag has not been pushed, delete and recreate the local tag after fixing the target commit.
|
||||
- If the tag has been pushed and the Release workflow fails, inspect failed job logs before changing anything.
|
||||
- Prefer rerunning failed workflow jobs for transient infrastructure failures.
|
||||
- If the pushed tag points to the wrong commit or release inputs are wrong, stop and ask before deleting or recreating the remote tag.
|
||||
- If GitHub Release creation succeeds but release notes are wrong, update docs and then update the GitHub Release body through a follow-up change.
|
||||
|
||||
## Quick prompt for future releases
|
||||
|
||||
When starting a future release, ask the user:
|
||||
|
||||
```text
|
||||
Please provide the release version, title, whether I should push the tag, the base release/tag, release-note highlights if any, raw Developer Notes thoughts, documentation language scope, validation level, and whether docs build should be skipped.
|
||||
```
|
||||
Reference in New Issue
Block a user