chore: merge main into release/1.17.1 and resort the api specs - #1028
Merged
Conversation
… editor test (#1021) * feat: put the writing standard first in the docs pipeline and add the editor test Rewrite dify-docs-write so the drafting turn holds the standard, the facts, and a reference page rather than the check procedures: reading indexed by stage, a fresh drafting agent, an outline gate keyed to reader questions, the research summary shown at the scope gate, three revision tiers, and an editor test that judges the writing before any linter. Open the style guide with "What a Good Page Does" and two worked examples from the Cloud New Agent pages. De-prescribe the CLI, guides, reader-test, release-sync, and feature-research packs; retire row and print vocabulary; state the translation, verification, and check rules once. Move repo-only facts into the guides index and reduce AGENTS.md to the entry point and repo rules. * fix: address review on the writing guides and pipeline Point the Columns block at the alt-text rule instead of restating it, lowercase the glossary row for agentic workflow with its plural note, scope the editor test to the English page in the guides index and the pipeline, and finish the fragment in the style guide's example lead-in. * fix: spell out the task-page exemplar's path in the pipeline and the editor test * fix: make pack reads conditional and align heading case and bold punctuation in the guides * fix: correct the Frame example, the zh punctuation after examples, and the glossary row's casing note
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
It includes very large, mechanically re-emitted OpenAPI JSON changes across three languages plus broad pipeline-rule updates that are best validated by a human review and the repo’s spec/parity gates.
Pull request overview
Resolves merge conflicts between main and release/1.17.1 by re-emitting the Service OpenAPI specs into a deterministic (alphabetically sorted) key order and carrying forward doc-writing pipeline and translation-guide updates from main, unblocking the subsequent release/1.17.1 → main merge.
Changes:
- Re-sorted the Service OpenAPI specs (en/zh/ja) to absorb
main’s key-order normalization while preservingrelease/1.17.1content edits. - Expanded/clarified the documentation writing pipeline and style/formatting guidance (including the new editor-test step).
- Updated API navigation label ordering metadata and refreshed the contact-sales links used in translation guidance.
File summaries
| File | Description |
|---|---|
| en/api-reference/openapi_service.json | Service OpenAPI spec re-emitted with deterministic key ordering while keeping 1.17.1 content. |
| zh/api-reference/openapi_service.json | Same as English spec: deterministic key ordering + preserved release content. |
| ja/api-reference/openapi_service.json | Same as English spec: deterministic key ordering + preserved release content. |
| tools/api-pipeline/nav_labels.json | Adds/records operation ordering for additional API groups/endpoints used by the API nav pipeline. |
| writing-guides/style-guide.md | Adds “What a Good Page Does” section and strengthens guidance on avoiding transcribed/dense prose. |
| writing-guides/formatting-guide.md | Adds component usage guidance (Columns, AccordionGroup) and clarifies UI-label bolding guidance. |
| writing-guides/index.md | Updates the recommended post-writing verification sequence to include dify-docs-editor-test. |
| writing-guides/glossary.md | Adds the “agentic workflow” term with zh/ja renderings and usage notes. |
| tools/translate/formatting-zh.md | Updates the standard Enterprise “contact sales” URL and adds more anti-translationese guidance. |
| tools/translate/formatting-ja.md | Updates the standard Enterprise “contact sales” URL. |
| AGENTS.md | Consolidates repo-wide agent instructions and points authors to the dify-docs-write pipeline. |
| .claude/skills/dify-docs-write/SKILL.md | Reframes the writing pipeline around reader-first drafting and integrates the editor-test concept into S7. |
| .claude/skills/dify-docs-write/references/task-analysis.md | Refines task-analysis definitions and depth labels (new page/rewrite/pre-release/update/correction). |
| .claude/skills/dify-docs-write/references/drafting-turn.md | Adds a drafting-turn checklist/reference to enforce reader-first drafting. |
| .claude/skills/dify-docs-editor-test/SKILL.md | Introduces the editor-test skill and its dispatch prompt template. |
| .claude/skills/dify-docs-terminology-check/SKILL.md | Strengthens terminology verification guidance (don’t treat doc-neighbor usage as evidence). |
| .claude/skills/dify-docs-release-sync/SKILL.md | Minor wording adjustments to align with the updated pipeline phrasing. |
| .claude/skills/dify-docs-reader-test/SKILL.md | Extends the reader-test prompt to capture “wanted but didn’t get” (judgment vs description/UI restatement). |
| .claude/skills/dify-docs-guides/SKILL.md | Clarifies the “don’t restate the page’s audience” rule with tighter rationale/examples. |
| .claude/skills/dify-docs-feature-research/SKILL.md | Minor wording adjustments for how targeted depth is described. |
| .claude/skills/dify-docs-env-vars/SKILL.md | Minor wording adjustments to reference the pipeline’s S4 gate consistently. |
| .claude/skills/dify-docs-api-reference/SKILL.md | Clarifies S6/S7 language (pack-modified stages, pipeline check chain wording). |
| .claude/skills/dify-docs-api-reference/references/spec-conventions.md | Improves readability (contents list) and tightens several conventions’ phrasing. |
| .claude/skills/dify-cli-docs/SKILL.md | Restructures/clarifies the CLI doc pack (readers, source of truth, house style, checks). |
Review details
- Files reviewed: 21/24 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This was referenced Sep 9, 2026
RiskeyL
added a commit
that referenced
this pull request
Sep 10, 2026
* docs: sync documentation for ce 1.17.1 (#1025) * docs: sync api specs and self-host docs for ce 1.17.1 * docs: document the difyctl help compact discovery flow * docs: retranslate team members zh/ja and correct the owner role * Correct markdown formatting in help.mdx Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * docs: add weaviate server upgrade path guide The existing v4 migration guide stops at server 1.27, but Dify now bundles 1.39 (langgenius/dify#38214). Existing deployments cannot jump that gap in one step: Weaviate does not test or support skipping minor versions. Adds a sibling page with the one-minor-at-a-time ladder and the two operational details that decide whether vectors survive it — graceful shutdown, which a hard kill silently costs you in HNSW recall, and the post-restart index-mount race. Cross-links both directions with the v4 page. en, zh and ja, with nav mirrored across all three sections. * fix: correct weaviate client versions in the compatibility matrix The matrix listed v4.17.0 for every release from 1.9.2 onward and capped server coverage at "tested up to 1.33.1". Both are stale: the client moved to 4.20.4 in 1.13.1 and 4.20.5 in 1.14.0, and the server bound was a moving target that went out of date rather than a real limit. Splits the client rows at their actual boundaries, replaces the tested-up-to note with the reason the server column has no upper bound, and points readers at the server upgrade path for external instances. Also replaces the hardcoded `pip install weaviate-client==4.17.0` fix with `uv sync`, so source installs get whatever version their checkout pins instead of being pinned to a version Dify stopped shipping. * fix: drop hard-coded step counts and correct a zh phrasing Review feedback on #940: - The warning said "twelve-step ladder" and the blast-radius note said "twelve-version jump" while the table lists thirteen rungs. Both counts are now phrased so they stay correct if the ladder changes. - zh used 回合到 for backporting, which does not read as Chinese. Rewritten as 合入. Applied to ja as well, where the same counts appeared as 10 段階 and 10 以上のバージョン. * fix: address review feedback on the weaviate upgrade path Re-validated the ladder end to end before rewriting: a volume seeded on 1.27.0 was walked through all 13 rungs, verified at each with both weaviate-client 4.20.5 and 4.22.0 (28/28 runs passed on object count, byte-exact vectors, near_vector recall, BM25 and a write round-trip). Sequencing: the page no longer claims the image bump has happened. langgenius/dify#38214 is still open and 1.17.0 still pins semitechnologies/weaviate:1.27.0, so the opening now describes a pin that is moving and reads correctly before and after that PR lands. Corrections from the re-run: - Object count used /v1/objects?limit=1 and read totalResults, which is the page length, not the collection total (always 1). Replaced with a GraphQL Aggregate query. - Every curl targeted localhost:8080, which the default compose file does not publish. All checks now run through docker compose exec against the container, using busybox wget since the image has no curl or python. - The hard-kill section claimed the index "recovers once rebuilt". It does not. A kill left 20 of 700 objects in the store but off the HNSW graph, and they stayed missing across three restarts and a rewrite, with nothing logged. Rewritten with the measured numbers and the real remedy. - The mount-race error text was wrong: no restart produced "non-existing index". The window returns 404 and a GraphQL "no schema is present", and it grows from under 0.3s to 4-9s at 1.31. Replaced with measurements. - Tail rungs moved to 1.37.15 and 1.38.13; the final rung stays at Dify's pin rather than the newest patch, so the ladder cannot overshoot it. - Weaviate supports three minor versions in total, not four. - docker compose stop -t 120 is now used in all four operational blocks, and sudo cp -a replaces cp -r in backup and rollback. - Client guidance points at the version each Dify release pins. - Pre-1.27 readers are routed to the v4 guide by version, not "1.19". - Dify does not set a distance metric; cosine is the server default. - Registry change to cr.weaviate.io is now explained at the ladder. Compatibility matrix restored to patch precision, corrected against the dependency history: 4.20.4 spans 1.13.1-1.13.3, 4.20.5 spans 1.14.0-1.16.1, and 1.17.0 ships 4.22.0. The uv sync block is split out with an explicit cd to the repo root, since it fails if copied from docker/. zh and ja mirrored in the same pass; zh description switched from 自托管 to the glossary's 自部署. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD * fix: move the final rung to weaviate 1.39.2 langgenius/dify#38214 now pins 1.39.2, so the ladder's last rung follows it. The rung must match the pin exactly: landing the volume on a different patch and then applying the compose file is the downgrade the page warns about. Validated the changed step rather than assuming it. Restored the volume snapshot taken after 1.38.13 and stepped it to 1.39.2: all checks pass with both weaviate-client 4.20.5 and 4.22.0, the index-mount gap is 7.8s (inside the documented 4-9s band), and totalResults behaves as documented (1 at limit=1, 200 at limit=250). Re-ran the hard-kill experiment on 1.39.2 too, which reproduces the same 20-of-700 unreachable objects with no recovery across restarts, so the measured figures now cite one version throughout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD * style: left-align the weaviate compatibility matrix columns Matches the separator style already used by the tables in weaviate-server-migration-path.mdx. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm * refactor: scope the weaviate upgrade path pr to english only Per review feedback on #940, the maintainers will handle the zh/ja alignment once the English content is settled. Drop the zh/ja copies of weaviate-server-migration-path, revert the zh/ja weaviate-v4-migration edits to main, and remove the matching zh/ja navigation entries so no section points at a missing page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm * fix: refresh weaviate tail rungs and correct the collection name Revalidates the ladder against the current weaviate tags: 1.37 and 1.38 have newer patches (1.37.16, 1.38.14). The final rung stays at 1.39.2, which is what langgenius/dify#38214 now pins, so the volume does not end up ahead of Dify's image. Also corrects the verification snippet. Dify's gen_collection_name_by_id replaces every hyphen in the knowledge base ID with an underscore, so a UUID pasted verbatim into Vector_index_<dataset_id>_Node never matches a real collection, and hyphens are invalid in a GraphQL field name, so the Aggregate count fails outright. The snippet now shows a concrete name and points at the schema check as the source of truth. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm * Update Weaviate Migration Guide for client v4 and server 1.27 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * chore: merge main into release/1.17.1 and resort the api specs (#1028) * feat: put the writing standard first in the docs pipeline and add the editor test (#1021) * feat: put the writing standard first in the docs pipeline and add the editor test Rewrite dify-docs-write so the drafting turn holds the standard, the facts, and a reference page rather than the check procedures: reading indexed by stage, a fresh drafting agent, an outline gate keyed to reader questions, the research summary shown at the scope gate, three revision tiers, and an editor test that judges the writing before any linter. Open the style guide with "What a Good Page Does" and two worked examples from the Cloud New Agent pages. De-prescribe the CLI, guides, reader-test, release-sync, and feature-research packs; retire row and print vocabulary; state the translation, verification, and check rules once. Move repo-only facts into the guides index and reduce AGENTS.md to the entry point and repo rules. * fix: address review on the writing guides and pipeline Point the Columns block at the alt-text rule instead of restating it, lowercase the glossary row for agentic workflow with its plural note, scope the editor test to the English page in the guides index and the pipeline, and finish the fragment in the style guide's example lead-in. * fix: spell out the task-page exemplar's path in the pipeline and the editor test * fix: make pack reads conditional and align heading case and bold punctuation in the guides * fix: correct the Frame example, the zh punctuation after examples, and the glossary row's casing note * style: sort openapi keys while preserving api navigation (#1022) --------- Co-authored-by: Stephen Zhou <hi@hyoban.cc> * docs: complete Weaviate 1.17.1 migration guidance * docs: stop Weaviate before final Dify upgrade * docs: handle Weaviate migration re-entry * fix: correct the pnpm version and unify the rate limit wording * docs: document the weaviate host port variables (#1033) EXPOSE_WEAVIATE_GRPC_PORT is new to the 1.17.1 build: dify#38214 gave it its first .env.example entry, though docker-compose.middleware.yaml has consumed it since 2025-10-13. EXPOSE_WEAVIATE_PORT is its twin and was already undocumented, so both land together in the Weaviate Service accordion. Both are middleware-stack only; the full Compose stack keeps Weaviate on an internal network. Each row links to the client-side endpoint variable it must be kept in sync with, which sits about 1100 lines away. --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Duda Nogueira <dudanogueira@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Stephen Zhou <hi@hyoban.cc> Co-authored-by: Yajing Wang <yajing@Yajings-MacBook-Air.local> Co-authored-by: Yajing Wang <101789361+Ill-donut@users.noreply.github.com>
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.
Unblocks the
release/1.17.1→mainPR, which currently conflicts.Cause
#1022 re-sorted the keys in all three
openapi_service.jsonfiles onmain.release/1.17.1edited the same three files in the pre-sort order via #1025. Git cannot reconcile a 16,884-line reordering with a 600-line content edit, so all three specs conflict.Resolution
Two facts make this mechanical rather than a judgement call:
main's change is a pure reorder. The merge base (236fcaa6) andmainparse to identical objects in all three languages — no content was added, removed, or changed by style: sort openapi keys while preserving api navigation #1022.json.dumps(obj, indent=2, ensure_ascii=False, sort_keys=True)reproducesmain's three files byte for byte.So the conflicts were resolved by re-emitting the release branch's spec content through that same emitter, rather than by hand-merging hunks.
Evidence
origin/release/1.17.1in all three languages: no 1.17.1 content was lost, and none ofmain's reordering was reverted.mainis exactly the 1.17.1 delta measured before the merge — en+605 −98, zh+613 −106, ja+613 −106. The 16,884-line reorder is fully absorbed.coverage failures: 0,TOTAL ISSUES: 0,TOTAL PARITY ISSUES: 0.Also carried from main
The writing-pipeline changes from #1021 (
.claude/skills/,writing-guides/,AGENTS.md,tools/translate/formatting-{zh,ja}.md) andtools/api-pipeline/nav_labels.jsonfrom #1022. Those auto-merged with no conflicts. 24 files total.Once this lands,
release/1.17.1→mainmerges cleanly.Tracking: DC-277.