search: document keyword search#55
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Hey @stefanhengl should this PR be shipped on Feb 15th? |
|
@MaedahBatool yes indeed, this documents a search language change we're shipping in 5.3 (https://github.com/sourcegraph/sourcegraph/issues/58815). |
Thanks @jtibshirani let's make this PR a draft so we don't merge it accidently. |
|
@MaedahBatool can you explain why we wouldn't want to merge the PR? Is there a docs freeze at the moment? |
No docs freeze but have we shipped Sourcegraph 5.3? An early docs release might confuse our readers for a feature change that hasn't shipped so far. |
|
@MaedahBatool and I caught up offline, and I explained the importance of merging these docs before the release so that we can (1) start to link to them from the UI, and (2) use our usual PR workflow to review and iterate on the docs. So I'm taking this out of draft mode now. |
jtibshirani
left a comment
There was a problem hiding this comment.
I wasn't able to view a preview, but the text looks good to me! I left a few comments.
| | [`/foo.*bar/`](https://sourcegraph.com/search?q=context:global+repo:%5Egithub%5C.com/sourcegraph/sourcegraph%24+/foo.*bar/&patternType=keyword) | Match the **regular expression** `foo.*bar`. We support [RE2 syntax](https://golang.org/s/re2syntax). | | ||
| | [`foo OR bar`](https://sourcegraph.com/search?q=context:global+foo+OR+bar&patternType=keyword) | Match documents containing `foo` _or_ `bar` anywhere in the document. | | ||
|
|
||
| Matching is case-insensitive (toggle the `Aa` button to change). |
There was a problem hiding this comment.
| Matching is case-insensitive (toggle the `Aa` button to change). | |
| Matching is case-insensitive by default (toggle the `Aa` button to change). |
| ### Keyword search (default) | ||
|
|
||
| Standard search matches literal patterns exactly, including puncutation like quotes. Specify regular expressions inside `/./code_search/reference`. | ||
| <Callout type="note" title="Experimental">New in version 5.3: Keyword search is in the experimental stage and enabled by default. Site administrators can disable keyword search globally by setting `experimentalFeatures.keywordSearch: false` in site settings. Users can override the setting in their user settings.</Callout> |
There was a problem hiding this comment.
I believe we decided on calling this 'beta' instead of 'experimental'. Looking at our docs for what experimental features mean, it doesn't seem like a good fit -- experimental features have limited support, have to be explicitly enabled, etc.
| Standard search matches literal patterns exactly, including puncutation like quotes. Specify regular expressions inside `/./code_search/reference`. | ||
| <Callout type="note" title="Experimental">New in version 5.3: Keyword search is in the experimental stage and enabled by default. Site administrators can disable keyword search globally by setting `experimentalFeatures.keywordSearch: false` in site settings. Users can override the setting in their user settings.</Callout> | ||
|
|
||
| Keyword search matches individual terms anywhere in the document or the filename. Specify regular expressions inside `/.../`. |
There was a problem hiding this comment.
Maybe we can add a line about exact matching using quotes before the line on regular expressions, since this is a key piece of syntax.
|
|
||
| ### Standard search | ||
|
|
||
| <Callout type="note" title="Experimental"> |
There was a problem hiding this comment.
It may be confusing to have an experimental (or beta) badge next to Standard search. Maybe we can remove this badge and just include the info about the toggle in the Keyword search callout above?
You can view the preview at this link: https://sourcegraph-docs-v2-git-document-ke-010214-sourcegraph-f8c71130.vercel.app/docs |
|
I just noticed something else to address: we use the term 'keyword' in these docs to mean 'filter name': https://sourcegraph.com/docs/code_search/reference/queries#keywords-all-searches. I think we need to update the terminology there to distinguish it from "keyword search". In general, it's unusual to call these "keywords" in the search context, they're usually called "filters". |
|
@stefanhengl the changes look good! Did you see my comment above?
|
e48d6ae to
30c6166
Compare
|
Sorry I had to force push, but a lot of files were moved around/deleted in the meantime and it was much easier to just do it from scratch. On top comes the change from @jtibshirani's comment |
jtibshirani
left a comment
There was a problem hiding this comment.
Thanks for fixing that! I think it's a lot clearer now.
|
Merging now to avoid running into more conflicts! |
Relates to https://github.com/sourcegraph/sourcegraph/pull/59779
With 5.3, keyword search will be the new default. Users can toggle between keyword search and standard search.