mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-09 14:34:43 +00:00
156393be0e
This tracks the snippets that probably should be converted to `// CONSOLE` or `// TESTRESPONSE` and fails the build if the list of files with such snippets doesn't match the list in `docs/build.gradle`. Setting the file looks like ``` /* List of files that have snippets that probably should be converted to * `// CONSOLE` and `// TESTRESPONSE` but have yet to be converted. Try and * only remove entries from this list. When it is empty we'll remove it * entirely and have a party! There will be cake and everything.... */ buildRestTests.expectedUnconvertedCandidates = [ 'plugins/discovery-azure-classic.asciidoc', ... 'reference/search/suggesters/completion-suggest.asciidoc', ] ``` This list is in `build.gradle` because we expect it to be fairly temporary. In a few months we'll have converted all of the docs and won't ned it any more. From now on if you add now docs that contain a snippet that shows an interaction with elasticsearch you have three choices: 1. Stick `// CONSOLE` on the interactions and `// TESTRESPONSE` on the responses. The build (specifically (`gradle docs:check`) will test that these interactions "work". If there isn't a `// TESTRESPONSE` snippet then "work" just means "Elasticsearch responds with a 200-level response code and no `WARNING` headers. This is way better than nothing. 2. Add `// NOTCONSOLE` if the snippet isn't actually interacting with Elasticsearch. This should only be required for stuff like javascript source code or `curl` against an external service like AWS or GCE. The snippet will not get "OPEN IN CONSOLE" or "COPY AS CURL" buttons or be tested. 3. Add `// TEST[skip:reason]` under the snippet. This will just skip the snippet in the test phase. This should really be reserved for snippets where we can't test them because they require an external service that we don't have at testing time. Please, please, please, please don't add more things to the list. After all, it sais there'll be cake when we remove it entirely! Relates to #18160