docs(ds-slack): document 11 new parameters and correct six statements, all seven languages - #512
Open
marevol wants to merge 4 commits into
Open
docs(ds-slack): document 11 new parameters and correct six statements, all seven languages#512marevol wants to merge 4 commits into
marevol wants to merge 4 commits into
Conversation
… update Bring ds-slack.rst up to date with fess-ds-slack's Phase 0-3 changes (20 -> 31 documented parameters, plus six behaviours that no longer match the implementation). - Add the 11 new parameters (advanced parameter table): connection timeout/retry tuning, exclude_archived, ignore_system_events, read_interval, max_content_length, and the new permission_sync / default_permissions ACL feature, with defaults verified against the plugin source. - Add team:read to the required OAuth scopes in every scope list; it was missing everywhere, and its absence silently multiplies API calls via a per-message chat.getPermalink fallback. - Flag ignore_system_events defaulting to true with a .. note:: since it silently reduces indexed document counts on upgrade. - Add a new "Permission Synchronization (ACL)" section covering fail-closed behaviour, the required users:read.email scope, and the Fess-login-name-must-match-Slack-email requirement. - Correct six inaccurate statements: archived-channel handling was backwards, the "0 messages" section described a silent-partial- success mode that was removed, the rate limit error code is `ratelimited` (not `rate_limited`) and now fails the crawl, the tier list omitted Tier 2 (conversations.list/users.list), and the 2025-05-29 Slack rate limit change does not apply to internal apps. - Delete the "exclude old messages" troubleshooting advice, since no such setting exists and incremental crawling was out of scope for this effort. - Document thread replies, system-event exclusion, DM/group-DM being out of scope, and Huddle/Clips having no crawlable API. Japanese is source; English is a translation with byte-identical parameter names, defaults, and code samples per this repo's convention. Only the 15.9 (development) tree is touched; 15.5-15.8 are unchanged, as are the other five languages (handled separately).
- Add the missing blank line after ".. note::" in the role=message.roles reminder, matching the other four new note blocks in this change and the ds-csv.rst convention. - Qualify the files.info entry in the Tier 4 list: the plugin's crawl path never calls files.info (only SlackClient exposes it, exercised by a unit test), so leaving it unqualified next to conversations.members's "(only when permission_sync=true)" wrongly implies normal crawling exercises Tier 4 via this method. - Add the companion fact to "Other Notes": disabling permission_sync does not retroactively remove roles already applied to previously indexed documents, mirroring the existing statement that enabling it does not retroactively secure already-indexed content.
Bring ds-slack.rst up to date in the five remaining languages, matching
the ja/en page from the previous two commits (20 -> 31 documented
parameters plus six behaviour corrections).
- Add the Advanced Parameters table (connection/retry tuning,
exclude_archived, ignore_system_events, read_interval,
max_content_length, permission_sync, default_permissions) with a
note that ignore_system_events now defaults to true.
- Add team:read to every required-scopes list and restructure the
OAuth scopes section into "always required" base scopes plus
additive blocks per optional feature, matching the corrected en
structure.
- Add the new "Permission Synchronization (ACL)" section: fail-closed
behaviour, the required users:read.email scope, and the
Fess-login-name-must-match-Slack-email requirement.
- Correct the same six inaccuracies fixed in ja/en: archived-channel
handling, the removed silent-partial-success crawl mode, the
ratelimited (not rate_limited) error code now failing the crawl, the
Tier 2 gap in the API tier list, and the 2025-05-29 Slack rate limit
change not applying to internal apps.
- Drop the "exclude old messages" troubleshooting advice (no such
setting exists).
- Document thread replies, system-event exclusion, and the DM/Huddle/
Clips scope exclusions.
Per-language fixes:
- ko: corrected five section-heading underlines that were one display
column short (title/underline width mismatch pre-dating this
change).
- es/fr: wrote correct accents throughout, including in untouched
neighbouring headings that had lost them.
- zh-cn: used full-width punctuation and the rst escaped space ("\ ")
wherever an inline literal meets CJK text, consistent with the rest
of the zh-cn tree.
Parameter names, defaults, error codes, scope names, and every code
sample remain byte-identical to ja/en, per this repo's translation
convention. Only the 15.9 (development) tree is touched.
Commit 539d5c7 added a blank line after ".. note::" in the "forgot role=message.roles" reminder for ja/en consistency, but the same block was written as new content in the five-language translation (a8b9ad9) without it. Add the blank line there too so all seven languages format this note block the same way. Checked all six note blocks in each of the five languages against ja; this was the only one that diverged.
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
1 participant
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
Bring the Slack data store page in line with the plugin. It documented 20 parameters where the code reads 31, and six of its statements contradicted the implementation.
All seven languages, 15.9 only. Japanese was written first and the rest translated from it, per the convention this repo's own history establishes.
The most damaging gap:
team:readwas missingteam.infois called unconditionally on every crawl. Without the scope it does not fail — it degrades: the permalink path falls back to onechat.getPermalinkcall per message, multiplying API usage enormously against a rate-limited endpoint. The scope was absent from the list in every language and every version. It is now listed as always required.The one silent behaviour change
ignore_system_eventsdefaults totrue. An existing installation that upgrades and changes nothing will index fewer documents, becausechannel_join,channel_leaveand fourteen other channel-administration subtypes are now dropped. This has a.. note::at the point of configuration and again in troubleshooting, in all seven languages.Eleven new parameters
connection_timeout,read_timeout,max_retry_count,retry_interval,executor_timeout,exclude_archived,ignore_system_events,read_interval,max_content_length,permission_sync,default_permissions— in a new "Advanced Parameters" table followingds-csv.rst's shape. Every default was traced to the constant that defines it rather than copied from a summary.max_filesizeandmax_content_lengthare documented as what they are: a transfer bound checked before download, and an extraction bound on how much text Tika produces. Neither substitutes for the other.Permission sync needs three things said plainly
permission_synccomputes roles; it does not apply them. A script must maprole=message.rolesor the feature costs its fail-closed skips and restricts nothing. It needsusers:read.email. And the Fess principal name must equal the Slack email — Fess builds search-time roles from the login name, so a mismatch means private content silently returns nothing for everyone.Those are two opposite failure modes — unrestricted content versus empty results — and they are stated separately in every language rather than merged.
Six corrections
exclude_archiveddefaults tofalse, so archived channels are crawledmissing_scopeis now fatal and fails the job; that silent-partial-success mode was deliberately removedrate_limitedratelimited, no underscore — and it now fails the crawl rather than skipping, after bounded retries honouringRetry-Afterconversations.listandusers.listare the binding ones, called at the start of every crawlAlso added
Thread replies are indexed — the word "thread" did not appear on the page at all. DM and group DM are out of scope. Huddle transcripts and Clips cannot be crawled; Slack has no API for them. And the error-handling contract: fatal and transient errors fail the job, channel-scoped errors warn and skip that channel.
Incidental repairs
Descripcion,envio,a ete envoye). A previous repair covered only 15.7 and 15.8. Fixed file-wide, not just in new prose.Verification
halt_level=5with no warnings. This is what actually validates CJK heading widths and inline-literal escaping;tools/check_headings.pyexits 1 at baseline from 150 pre-existing warnings in unrelated files, and this change adds none.list-tableand::block counts match across all seven; heading structure is identical (41 headings, same H1/H2/H3 sequence).:widths:values that exist in this tree are used.