docs(15.9): correct eight places where the docs disagree with the product - #553
Merged
Merged
Conversation
…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.
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
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.
api/admin/api-admin-backup.rstGET /api/admin/backup/file/fess_config.bulk/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.rstsort:makes the search failsort:does not raise an error. The query is escaped and searched again, so the results are not sorted and usually nothing is found. Only thesortrequest parameter returns 400.config/search-advanced.rstquery.additional.api.response.fieldsadds fields to the API responsequery.additional.response.fields. There is now a note and an example that sets both.api/api-search.rst,api/admin/api-admin-searchlist.rstrecord_count_relationiseq/gteEQUAL_TO/GREATER_THAN_OR_EQUAL_TO. These are the values the API returns and the bundled OpenAPI definition lists.admin/log-guide.rstsearch.logsearchlog.logconfig/admin-logging.rstlog4j2.xmlalso deletes compressed files by age: 90 days forfess.log,fess-llm.logandsearchlog.log, and 360 days foraudit.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#are comments.admin/stopwords-guide.rsten/stopwords.txtis removed fromcontentandtitle. It can still match throughcontent_jaof documents detected as Japanese, because language-specific fields are added to the query based on the request language.Verification
SearchHelper/TermQueryCommand/QueryStringBuilder,QueryFieldConfigand 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.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.
config/properties.rstquery.additional.response.fields,query.additional.api.response.fieldsandquery.additional.scroll.response.fieldsapi/admin/api-admin-backup.rstfess.json/doc.jsonare scrolled like a.bulkidfess_indices/fess.json,fess_indices/fess/doc.json) asapplication/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.jsonis also listed among the ids that need a trailing/.config/search-scroll.rstquery.additional.scroll.response.fields=contentmakes/api/v2/documents/allreturncontentcontentby default. The example now sets bothquery.additional.scroll.response.fields=contentandquery.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) andSearchHelper.tools/gen_properties_doc.py --checkandtools/test_gen_properties_doc.pypass. None of the changed files gets a new docutils warning.