Skip to content

docs(15.9): correct eight places where the docs disagree with the product - #553

Merged
marevol merged 2 commits into
mainfrom
docs/159-behaviour-mismatches
Sep 24, 2026
Merged

marevol merged 2 commits into
mainfrom
docs/159-behaviour-mismatches

Conversation

@marevol

@marevol marevol commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A release test of 15.9 found eight places where the documentation describes behaviour that Fess does not have. The same text is in 15.8. This PR fixes the 15.9 tree in all seven languages.

Page Was Now
api/admin/api-admin-backup.rst GET /api/admin/backup/file/fess_config.bulk A path whose last segment contains a dot and has no trailing / is treated as a static file request and never reaches the API, so it returns 404. The page now says to end such ids with /, and both curl examples do.
user/search-sort.rst An unsupported field or order in sort: makes the search fail In the query, an unsupported sort: does not raise an error. The query is escaped and searched again, so the results are not sorted and usually nothing is found. Only the sort request parameter returns 400.
config/search-advanced.rst query.additional.api.response.fields adds fields to the API response That key only extends the search API's allow-list. The field must also be fetched through query.additional.response.fields. There is now a note and an example that sets both.
api/api-search.rst, api/admin/api-admin-searchlist.rst record_count_relation is eq / gte EQUAL_TO / GREATER_THAN_OR_EQUAL_TO. These are the values the API returns and the bundled OpenAPI definition lists.
admin/log-guide.rst search.log searchlog.log
config/admin-logging.rst Rotation by size, with at most 10 generations The bundled log4j2.xml also deletes compressed files by age: 90 days for fess.log, fess-llm.log and searchlog.log, and 360 days for audit.log. The page now lists these periods and the properties that set them, and says the 10-file limit applies per date. The French page also said 10 MB where the limit is 100 MB.
admin/stopwords-guide.rst Copied from the mapping guide ("source" / "target" characters) The page describes stopwords and the single word field on the screen. It also gives the download and upload format: one word per line, and lines starting with # are comments.
admin/stopwords-guide.rst No note on scope A new note says each stopwords file is used only by the analyzer for its own language. A word added only to en/stopwords.txt is removed from content and title. It can still match through content_ja of documents detected as Japanese, because language-specific fields are added to the query based on the request language.

Verification

  • Checked each statement against the Fess source: the backup API action and LastaFlute request routing, SearchHelper / TermQueryCommand / QueryStringBuilder, QueryFieldConfig and the v2 search handlers, log4j2.xml, the stopwords admin form, JSP and dictionary file parser, and the analyzers and dynamic templates in the bundled index settings.
  • Parsed every changed file with docutils (doctitle_xform=False). Each file still has exactly one top-level section, and none has a new warning.

Follow-up: how the response-field keys combine

A second commit covers three more places, all about fields that are fetched from the index and fields the API is allowed to return.

Page Was Now
config/properties.rst Short descriptions of query.additional.response.fields, query.additional.api.response.fields and query.additional.scroll.response.fields Regenerated from the rewritten comments in codelibs/fess#3490. They explain that one set of keys fetches a field and the other lets the API return it. Only these three rows change, and the per-language catalogues get the new msgids. Like every other entry in those catalogues, they are not translated yet. Merge this PR after codelibs/fess#3490.
api/admin/api-admin-backup.rst fess.json / doc.json are scrolled like a .bulk id The download returns the mapping definition file itself (fess_indices/fess.json, fess_indices/fess/doc.json) as application/octet-stream. The ID table now has a row for them. The note now says that the API only downloads and that files are restored from the Backup page in the admin screen. fess.json is also listed among the ids that need a trailing /.
config/search-scroll.rst query.additional.scroll.response.fields=content makes /api/v2/documents/all return content The scroll API also filters every document through the API response allow-list, which does not include content by default. The example now sets both query.additional.scroll.response.fields=content and query.additional.api.response.fields=content, and both notes explain why both are needed.

Verified against ApiAdminBackupAction#get$file, AdminBackupAction (upload and mapping-file paths), ScrollSearchHandler#filterDoc, QueryFieldConfig (default scroll fields and API allow-list) and SearchHelper. tools/gen_properties_doc.py --check and tools/test_gen_properties_doc.py pass. None of the changed files gets a new docutils warning.

…duct

A release test found these pages describing behaviour that Fess does
not have (the same text is in 15.8):

- Backup API: a path whose last segment contains a dot and has no
  trailing slash is treated as a static file request and never reaches
  the action, so /api/admin/backup/file/fess_config.bulk returns 404.
  Say to end such ids with "/" and fix both curl examples.
- Sort search: an unsupported field or order in sort: inside the query
  does not raise an error. The query is escaped and searched again, so
  it is not sorted and usually finds nothing. Only the sort request
  parameter returns 400.
- Response fields: query.additional.api.response.fields only extends
  the allow-list of the search API; the field also has to be fetched
  through query.additional.response.fields. Explain both and show an
  example.
- record_count_relation is EQUAL_TO or GREATER_THAN_OR_EQUAL_TO (the
  TotalHits relation name), not eq/gte, in the search API and the admin
  search list API.
- The search log file is searchlog.log, not search.log.
- Log rotation: the bundled log4j2.xml also deletes compressed files by
  age (fess.log and fess-llm.log 90 days, searchlog.log 90 days,
  audit.log 360 days). Document the periods and the properties that set
  them, and that the 10-file limit applies per date. The French page
  also said 10 MB instead of 100 MB.
- Stopwords guide: it was copied from the mapping guide and described
  source/target fields. The screen has a single word field. Rewrite the
  overview, the field description and the download/upload format.
- Stopwords guide: add a note that each stopwords file is used only by
  its language's analyzer. A word in en/stopwords.txt is removed from
  content/title but can still match through content_ja of documents
  detected as Japanese.

All seven languages, 15.9 tree only.
…combine

- config/properties: regenerate the descriptions of
  query.additional.response.fields, query.additional.api.response.fields and
  query.additional.scroll.response.fields from the rewritten comments in
  fess_config.properties (codelibs/fess#3490). The catalogues gain the new
  msgids and drop the old ones; like every other entry they are untranslated.
- api/admin/api-admin-backup: fess.json and doc.json are not scrolled like a
  .bulk id. The download returns the mapping definition file itself
  (fess_indices/fess.json, fess_indices/fess/doc.json) as
  application/octet-stream. Add a row for them, replace the wrong note with
  one saying the API only downloads and restoring is done from the admin
  Backup page, and list fess.json among the ids that need a trailing slash.
- config/search-scroll: /api/v2/documents/all filters every document through
  the API response allow-list, which does not contain content. Adding
  content to query.additional.scroll.response.fields only fetches it; it
  also has to be added to query.additional.api.response.fields.
@marevol
marevol merged commit 1e88b2e into main Sep 24, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant