docs(release-notes): rewrite resources/release_notes.md as VSAG 1.0 launch notes#2071
Draft
wxyucs wants to merge 6 commits into
Draft
docs(release-notes): rewrite resources/release_notes.md as VSAG 1.0 launch notes#2071wxyucs wants to merge 6 commits into
wxyucs wants to merge 6 commits into
Conversation
Add a stub resources/migration_to_1_0.md in both English and Chinese, and wire it into the website SUMMARY under Resources. Content will be filled in by follow-up commits on this branch. Refs: antgroup#2069 Signed-off-by: Xiangyu Wang <wxyucs@gmail.com> Assisted-by: OpenCode:claude-opus-4.7
Fill in the first concrete section of the Migration to 1.0 guide: - An at-a-glance status table covering the seven main migration topics (deprecated indexes, search API, allocator field, CalDistanceById, serialization, C ABI). - Step-by-step build- and search-time mapping for hnsw -> hgraph, including the change of build-config sub-object key from 'hnsw' to 'index_param' and the required base_quantization_type field. - Recommendation hierarchy for diskann -> ivf / hybrid memory-disk. - Note that hgraph is now the primary example across guide pages. Refs: antgroup#2069 Signed-off-by: Xiangyu Wang <wxyucs@gmail.com> Assisted-by: OpenCode:claude-opus-4.7
Document the deprecated KnnSearch(query, k, SearchParam&) overload and the migration to SearchWithRequest(SearchRequest): - Field-by-field mapping table from SearchParam to SearchRequest. - Highlight new capabilities only SearchRequest exposes (mode_, range search, attribute / bitset filters, expected_labels_). - Before/after C++ snippets for KNN search. - Range-search snippet showing that one struct now drives both modes. Refs: antgroup#2069 Signed-off-by: Xiangyu Wang <wxyucs@gmail.com> Assisted-by: OpenCode:claude-opus-4.7
Fill out the rest of the Migration to 1.0 guide: - CalDistanceById typo, intent to rename to CalcDistancesById in a future release, and a wrapper pattern to soften the eventual migration. - Serialization compatibility statement (forward-compatible from 0.18.x; reverse not supported; re-serialize after upgrading). - Default-value and behavioral changes (MKL off by default; HGraph default knobs; opt-in support_remove / support_duplicate / store_raw_vector). - Build-system and packaging notes (clang-format/-tidy 15 pin, ABI variants, Python wheel, npm package). - Step-by-step upgrade checklist. - Drop the draft banner; replace it with a lightweight tracking note and a See-also section. With this commit the page is feature-complete pending review. Refs: antgroup#2069 Signed-off-by: Xiangyu Wang <wxyucs@gmail.com> Assisted-by: OpenCode:claude-opus-4.7
- Remove broken links to api_stability.md (page does not yet exist); reword as a planned follow-up tracked in antgroup#2069. - Reword the 'hgraph as the default example' paragraph to make clear that guide/create_index.md, resources/index_parameters.md and advanced/serialization.md will be updated in follow-up PRs, also tracked in antgroup#2069. Applies to both EN and ZH copies of resources/migration_to_1_0.md. Refs: antgroup#2069 Signed-off-by: Xiangyu Wang <wxyucs@gmail.com> Assisted-by: OpenCode:claude-opus-4.7
The previous resources/release_notes.md was generic boilerplate that
only pointed readers at GitHub Releases. Replace it with a real 1.0
launch page so the documentation site has a canonical, browsable
changelog for the 1.x line.
Content is organized to mirror docs/docs/en/src/resources/roadmap_2025.md
so each roadmap commitment maps to a concrete section: Highlights,
Indexes (HGraph, IVF, SINDI, Pyramid, BruteForce, WARP), Quantization
(RabitQ / PQ / SQ4 / SQ8), Data types (FP32/INT8/BF16/FP16/sparse/
MultiVector), Search API (SearchRequest, CalcDistancesById), Platforms
and packaging (SIMD matrix, macOS, MKL opt-in, system OpenBLAS),
Resource isolation and observability (per-index/per-search allocators,
search statistics), Tooling and ecosystem (pyvsag, Node.js bindings,
eval_performance, HTTP monitor), Breaking changes (linking to the
companion Migration to VSAG 1.0 page), Known issues, Acknowledgments.
The exact 1.0 release date is left as 'target: 2026, exact date TBD'
and will be filled in during the 1.0 RC cycle. Pre-1.0 (0.15 / 0.16 /
0.18) history continues to live on GitHub Releases and is linked from
the top of the page.
EN and ZH copies remain file-name parallel and content-equivalent. The
Per-Search Allocator / Index Introspection / Index Lifecycle Management
links use the actual existing filenames in docs/docs/{en,zh}/src/advanced/.
This is Phase 1 #2 of the VSAG 1.0 documentation readiness tracker.
Refs: antgroup#2069
Stacked-on: antgroup#2070
Signed-off-by: Xiangyu Wang <wxyucs@gmail.com>
Assisted-by: OpenCode:claude-opus-4.7
wxyucs
added
kind/documentation
Contributor
Merge ProtectionsYour pull request matches the following merge protections and will not be merged until they are valid. 🔴 ⛓️ Depends-On RequirementsWaiting for
This rule is failing.Requirement based on the presence of
🟢 Require kind labelWonderful, this rule succeeded.
🟢 Require version labelWonderful, this rule succeeded.
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for the VSAG 1.0 release, including detailed migration guides and release notes in both English and Chinese. The new documentation covers the transition from version 0.18.x, highlighting the deprecation of legacy indexes in favor of HGraph and IVF, the introduction of the new SearchRequest API, and various performance and resource isolation improvements. Review feedback points out several necessary corrections: resolving contradictions between the release notes and migration guide regarding serialization compatibility, clarifying that the CalcDistancesById rename is a planned future update, fixing Markdown rendering for pointer types, and improving document navigation by converting plain text references into internal links.
| - `SearchParam` and the old `KnnSearch(query, k, SearchParam&)` overload | ||
| remain available but are marked `[[deprecated]]`. The full mapping is | ||
| in [Migration to VSAG 1.0](migration_to_1_0.md). | ||
| - `CalDistanceById` (batch) is being renamed to `CalcDistancesById` with |
Contributor
There was a problem hiding this comment.
The current phrasing suggests that CalcDistancesById is already available in 1.0.0 as a replacement for the misspelled CalDistanceById. However, according to the migration guide and the current codebase (include/vsag/index.h), this rename is only planned and the new name does not exist yet. To avoid user confusion and compilation errors, it should be clarified as a planned update.
Suggested change
| - `CalDistanceById` (batch) is being renamed to `CalcDistancesById` with | |
| - CalDistanceById (batch) is planned to be renamed to CalcDistancesById in a future release; the current name remains available. See [Calculate Distance by ID](../advanced/calc_distance_by_id.md) and issue [#2068](https://github.com/antgroup/vsag/issues/2068). |
Comment on lines
+174
to
+175
| Serialization: 0.18 snapshots are **not** guaranteed to deserialize on | ||
| 1.0; rebuild on the new release. See *Migration*. |
Contributor
There was a problem hiding this comment.
This statement contradicts the migration guide (migration_to_1_0.md), which explicitly states that VSAG 1.0 can read 0.18.x serialized indexes and that the format is compatible on the forward path. The release notes should be updated to reflect this compatibility to avoid unnecessary concern for users upgrading.
Suggested change
| Serialization: 0.18 snapshots are **not** guaranteed to deserialize on | |
| 1.0; rebuild on the new release. See *Migration*. | |
| Serialization: 0.18 snapshots are readable by 1.0 (forward compatibility). It is recommended to re-serialize once to adopt 1.0 layout improvements. See [Migration](migration_to_1_0.md). |
| - `SearchParam` 与旧的 `KnnSearch(query, k, SearchParam&)` 仍然可用， | ||
| 但已标记 `[[deprecated]]`。完整对照见 | ||
| [升级到 VSAG 1.0](migration_to_1_0.md)。 | ||
| - `CalDistanceById`（批量接口）正在改名为 `CalcDistancesById`，返回值 |
Contributor
There was a problem hiding this comment.
此处说明暗示 CalcDistancesById 已在 1.0.0 中可用。但实际上该重命名仅在计划中，目前代码中尚不存在该名称。建议明确其为未来计划，以免用户在尝试使用新名称时遇到编译错误。
Suggested change
| - `CalDistanceById`（批量接口）正在改名为 `CalcDistancesById`，返回值 | |
| - CalDistanceById（批量接口）计划在未来版本中重命名为 CalcDistancesById，返回值语义将保持统一；目前旧名仍可继续使用。见 [按 ID 计算距离](../advanced/calc_distance_by_id.md) 与 Issue [#2068](https://github.com/antgroup/vsag/issues/2068)。 |
Comment on lines
+152
to
+153
| 序列化方面：0.18 序列化文件**不保证**能在 1.0 上反序列化；建议在新版本 | ||
| 重建索引。详见 *Migration*。 |
Contributor
There was a problem hiding this comment.
此处关于序列化兼容性的描述与迁移指南冲突。1.0 版本实际上支持读取 0.18 版本的快照（前向兼容）。建议修正此处的描述以保持文档一致性。
Suggested change
| 序列化方面：0.18 序列化文件**不保证**能在 1.0 上反序列化；建议在新版本 | |
| 重建索引。详见 *Migration*。 | |
| 序列化方面：1.0 版本支持读取 0.18 版本的快照（前向兼容）；建议在升级后重新序列化以采用新的布局优化。详见 [升级到 VSAG 1.0](migration_to_1_0.md)。 |
| | `parameters` (`const std::string&`) | `params_str_` (`std::string`) | The JSON parameter string (e.g. `{"hgraph": {"ef_search": 200}}`). | | ||
| | `filter` | `filter_` + `enable_filter_ = true` | The callback `Filter` object. Must explicitly enable. | | ||
| | `allocator` | `search_allocator_` | Per-search arena allocator. See [Per-Search Allocator](../advanced/search_allocator.md). | | ||
| | `iter_ctx` | `p_iter_ctx_` + `enable_iterator_search_ = true` | Note the `**` shape — `SearchRequest` takes `IteratorContext**`. | |
Contributor
There was a problem hiding this comment.
The use of ** without escaping or backticks will likely be rendered as bold text in Markdown, which obscures the technical meaning (pointer-to-pointer). Using escaped asterisks is a safe way to fix this without using backticks in the suggestion.
Suggested change
| | `iter_ctx` | `p_iter_ctx_` + `enable_iterator_search_ = true` | Note the `**` shape — `SearchRequest` takes `IteratorContext**`. | | |
| | iter_ctx | p_iter_ctx_ + enable_iterator_search_ = true | Note the \*\* shape — SearchRequest takes IteratorContext\*\*. | |
Comment on lines
+325
to
+328
| - Serialization-format compatibility statement. | ||
| - Default-value and behavioral changes. | ||
| - Build-system / packaging notes. | ||
| - Step-by-step upgrade checklist. |
Contributor
There was a problem hiding this comment.
These items in the "See also" section are plain text and do not function as links. They should be converted to internal Markdown links to improve navigation within the document.
Suggested change
| - Serialization-format compatibility statement. | |
| - Default-value and behavioral changes. | |
| - Build-system / packaging notes. | |
| - Step-by-step upgrade checklist. | |
| - [Serialization compatibility](#serialization-compatibility)\n- [Default-value and behavioral changes](#default-value-and-behavioral-changes)\n- [Build-system and packaging notes](#build-system-and-packaging-notes)\n- [Upgrade checklist](#upgrade-checklist) |
Comment on lines
+295
to
+298
| - 序列化格式兼容性声明。 | ||
| - 默认值与行为变化。 | ||
| - 构建系统 / 打包相关说明。 | ||
| - 升级操作清单。 |
Contributor
There was a problem hiding this comment.
“参考”部分中的这些条目目前是纯文本。建议将其转换为内部链接，以便用户快速跳转到相应章节。
Suggested change
| - 序列化格式兼容性声明。 | |
| - 默认值与行为变化。 | |
| - 构建系统 / 打包相关说明。 | |
| - 升级操作清单。 | |
| - [序列化兼容性](#序列化兼容性)\n- [默认值与行为变化](#默认值与行为变化)\n- [构建系统与打包说明](#构建系统与打包说明)\n- [升级操作清单](#升级操作清单) |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR rewrites the website release notes into VSAG 1.0 launch notes (EN+ZH) and wires the new 1.0 migration guide into the docs navigation, aligning the “Resources” section with the 1.0 documentation readiness tracker.
Changes:
- Rewrite
resources/release_notes.md(EN+ZH) into structured VSAG 1.0.0 launch notes with cross-links to related docs. - Add
resources/migration_to_1_0.md(EN+ZH) and link it fromSUMMARY.md(EN+ZH).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/docs/en/src/SUMMARY.md | Adds the “Migrating to VSAG 1.0” entry under Resources. |
| docs/docs/zh/src/SUMMARY.md | Adds the Chinese “升级到 VSAG 1.0” entry under 资源. |
| docs/docs/en/src/resources/release_notes.md | Replaces boilerplate with VSAG 1.0 launch notes and links to migration/advanced pages. |
| docs/docs/zh/src/resources/release_notes.md | Chinese counterpart of the 1.0 launch notes rewrite. |
| docs/docs/en/src/resources/migration_to_1_0.md | Adds an English 0.18→1.0 migration guide with code mapping examples. |
| docs/docs/zh/src/resources/migration_to_1_0.md | Adds a Chinese 0.18→1.0 migration guide with parallel structure/content. |
Comments suppressed due to low confidence (8)
docs/docs/en/src/resources/release_notes.md:106
- This section claims
SearchParam/KnnSearch(..., SearchParam&)are marked[[deprecated]], but the public API currently only includes that marker in doc comments (not as an actual C++[[deprecated]]attribute on the struct/function). Either add a real deprecation attribute in the headers or reword this to avoid implying compiler-level deprecation.
- `SearchParam` and the old `KnnSearch(query, k, SearchParam&)` overload
remain available but are marked `[[deprecated]]`. The full mapping is
in [Migration to VSAG 1.0](migration_to_1_0.md).
docs/docs/en/src/resources/release_notes.md:136
- The release notes say search statistics like
io_cnt/io_time_msare “exposed throughSearchRequestreasoning”, butSearchRequest(public header) has no fields for returning these counters andSearchWithRequestreturns only aDatasetPtr. Please update the text to reflect the actual public API for retrieving statistics/observability data (or remove this claim if it’s not externally available).
- **Search statistics** — `io_cnt`, `io_time_ms`, and other counters
exposed through `SearchRequest` reasoning.
docs/docs/zh/src/resources/release_notes.md:92
- 这里写到
SearchParam/KnnSearch(..., SearchParam&)已标记[[deprecated]]，但当前 public header 里只是注释里出现[[deprecated]]，并没有真实的 C++[[deprecated]]属性。建议要么在头文件里真正加上 deprecate 属性，要么改写文案避免误导。
- `SearchParam` 与旧的 `KnnSearch(query, k, SearchParam&)` 仍然可用，
但已标记 `[[deprecated]]`。完整对照见
[升级到 VSAG 1.0](migration_to_1_0.md)。
docs/docs/zh/src/resources/release_notes.md:120
- 这里说
io_cnt、io_time_ms等统计通过SearchRequestreasoning 暴露，但 public 的SearchRequest/SearchWithRequest接口没有用于返回这些计数器的字段（SearchWithRequest只返回DatasetPtr）。请改成实际可用的对外获取方式，或删除这条以免误导。
- **检索统计** —— `io_cnt`、`io_time_ms` 等计数器通过 `SearchRequest`
reasoning 暴露;
docs/docs/en/src/resources/migration_to_1_0.md:234
- This section asserts 1.0 can read 0.18.x serialized artefacts via all interfaces, which conflicts with the 1.0 release notes on the same branch (“0.18 snapshots are not guaranteed to deserialize on 1.0”). Please align these docs and ensure the migration guide reflects the supported/unsupported compatibility story.
VSAG 1.0 can **read** indexes serialized by 0.18.x via any of the three
serialization interfaces (`BinarySet` / `ReaderSet`, file streams, custom
`WriteFuncType`); the on-disk layout and metadata format are compatible
on the forward path.
docs/docs/en/src/resources/migration_to_1_0.md:306
- The upgrade checklist tells users to “Load 0.18.x artefacts with the 1.0 binary” as part of validation, which contradicts the release notes’ statement that 0.18 snapshots are not guaranteed to deserialize on 1.0. Please update the checklist to match the actual compatibility expectation (likely: rebuild or treat deserialization as best-effort).
5. **Validate serialization round-trip.** Load 0.18.x artefacts with the
1.0 binary, then re-serialize and reload.
docs/docs/zh/src/resources/migration_to_1_0.md:217
- 这里断言 1.0 可读取 0.18.x 的序列化产物（所有接口均可），但与本 PR 的版本日志“0.18 序列化文件不保证能在 1.0 上反序列化”相矛盾。请对齐两份文档并确认真实的支持范围，再给出一致结论。
VSAG 1.0 通过三种序列化接口（`BinarySet` / `ReaderSet`、文件流、
自定义 `WriteFuncType`）均可**读取** 0.18.x 序列化产物；磁盘布局与
元数据格式在前向方向上兼容。
docs/docs/zh/src/resources/migration_to_1_0.md:279
- 升级清单建议“用 1.0 二进制加载 0.18.x 产物…再次加载”，这与版本日志里“0.18 不保证能在 1.0 反序列化”的表述冲突。请更新清单步骤以匹配实际兼容性预期（例如强调重建/尽力而为）。
5. **序列化往返验证。** 用 1.0 二进制加载 0.18.x 产物，重新序列化后
再次加载。
Comment on lines
+64
to
+66
| - Reasoning instrumentation: pass a `QueryContext` to collect | ||
| per-search diagnostics (visited nodes, hop count, distance | ||
| computations) without changing the result format. |
Comment on lines
+55
to
+56
| - Reasoning 诊断：通过 `QueryContext` 收集每次检索的访问节点、跳数、 | ||
| 距离计算次数等，不影响检索结果格式。 |
| | `Index::KnnSearch(query, k, SearchParam&)` | Deprecated overload | Switch to `Index::SearchWithRequest(SearchRequest)` | | ||
| | `SearchParam::allocator` | Deprecated field | Use `SearchRequest::search_allocator_` | | ||
| | `Index::CalDistanceById` (batch) | Kept (typo'd name) | Continue to use; a correctly-spelled `CalcDistancesById` is planned (see [#2068](https://github.com/antgroup/vsag/issues/2068)) | | ||
| | Serialized indexes from 0.18.x | Readable by 1.0 | Re-serialize after upgrade to pick up any layout improvements | |
| | `Index::KnnSearch(query, k, SearchParam&)` | 已弃用的重载 | 改用 `Index::SearchWithRequest(SearchRequest)` | | ||
| | `SearchParam::allocator` | 已弃用字段 | 改用 `SearchRequest::search_allocator_` | | ||
| | `Index::CalDistanceById`（批量） | 保留（拼写错误的名字） | 继续使用；正确拼写的 `CalcDistancesById` 在规划中（见 [#2068](https://github.com/antgroup/vsag/issues/2068)） | | ||
| | 0.18.x 序列化产物 | 1.0 可读 | 升级后建议重新序列化以采用新的布局优化 | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/docs/{en,zh}/src/resources/release_notes.mdfrom generic boilerplate into a real VSAG 1.0 launch page.resources/roadmap_2025.mdso each 1.0 roadmap commitment is reflected by a concrete section.This is Phase 1 #2 of the 1.0 documentation readiness tracker.
Sections in the new 1.0 release notes
extra_infoSearchRequest,CalcDistancesById, range searchpyvsag, Node.js bindings,eval_performance, HTTP monitor serverThe exact 1.0 release date is left as target: 2026, exact date TBD and will be filled in during the 1.0 RC cycle. Pre-1.0 (0.15 / 0.16 / 0.18) history continues to live on GitHub Releases and is linked from the top of the page.
Notes for reviewers
docs/docs/en/src/resources/release_notes.mddocs/docs/zh/src/resources/release_notes.mddocs/docs/{en,zh}/src/. Themigration_to_1_0.mdlink resolves via docs: add Migrating to VSAG 1.0 guide (EN+ZH) #2070.Labels
kind/documentationversion/1.0created-by-AImodule/docsRefs: #2069
Depends-on: #2070