Skip to content

Commit 1a8dedf

Browse files
sarahssarahs
committed
bunch of edits
1 parent 642e669 commit 1a8dedf

1 file changed

Lines changed: 58 additions & 34 deletions

File tree

‎contributing/search.md‎

Lines changed: 58 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
1-
## Search
1+
# Search
2+
3+
## Table of contents
4+
- [Overview](#overview)
5+
- [How it works](#how-it-works)
6+
- [Manual sync from a checkout](#manual-sync-from-a-checkout)
7+
- [Build without sync (dry run)](#build-without-sync-dry-run)
8+
- [Build and sync](#build-and-sync)
9+
- [Label-triggered workflow](#label-triggered-workflow)
10+
- [Files](#files)
11+
- [GitHub Actions workflow files](#github-actions-workflow-files)
12+
- [Code files](#code-files)
13+
14+
15+
## Overview
216

317
This site's search functionality is powered by [Algolia](https://www.algolia.com), a third-party service.
418

@@ -10,65 +24,75 @@ To see all existing search-related issues and pull requests, visit [github.com/g
1024

1125
---
1226

13-
## How it Works
27+
## How it works
1428

1529
The search data is synced automatically using a [GitHub Actions workflow](.github/workflows/sync-algolia-search-indices.yml) that is triggered by pushes to the `main` branch. This process generates structured data for all pages on the site, compares that data to what's currently on Algolia, then adds, updates, or removes indices based on the diff of the local and remote data, being careful not to create duplicate records and avoiding any unnecessary (and costly) indexing operations.
1630

17-
The Actions workflow usually takes about five minutes, and the progress can be viewed (by GitHub employees) in the [Actions tab](https://github.com/github/docs/actions?query=workflow%3AAlgolia) of the repo.
18-
19-
## Development
31+
The Actions workflow progress can be viewed (by GitHub employees) in the [Actions tab](https://github.com/github/docs/actions?query=workflow%3AAlgolia) of the repo.
2032

21-
In cases where a publicity event like GitHub Satellite or GitHub Universe demands a very tight shipping window, it is also possible to manually sync the indices with Algolia's servers from your local checkout of the repo, before your feature branch is merged to main. Manually syncing the indices can also be useful to test an unreleased GitHub Enterprise version or a translated language (Portuguese, Chinese, etc) that is not yet in production.
33+
## Manual sync from a checkout
2234

23-
To sync the indices from your development environment:
35+
It is also possible to manually sync the indices to Algolia from your local checkout of the repo, before your branch is merged to `main`.
2436

25-
1. Make sure the two required environment variables `ALGOLIA_APPLICATION_ID` and `ALGOLIA_API_KEY` are set in your `.env` file. These can be retrieved from the [Algolia site](https://www.algolia.com/apps/ZI5KPY1HBE/api-keys/all).
26-
2. Run `npm run sync-search-dry-run`. This takes a while to complete. It will prepare, test, and validate all the indices without actually uploading anything to Algolia's servers.
27-
3. Run `npm run sync-search` to prepare the indices again and upload them to the Algolia servers.
37+
**Prerequisite:** Make sure the environment variables `ALGOLIA_APPLICATION_ID` and `ALGOLIA_API_KEY` are set in your `.env` file. You can find these values on [Algolia](https://www.algolia.com/apps/ZI5KPY1HBE/api-keys/all).
2838

29-
## Build indices for a specific language and/or version
39+
### Build without sync (dry run)
3040

31-
You can optionally build indices for a given language and/or a version. This is much faster than building all the indices.
32-
33-
You can build them as a dry run, which creates the index locally but does not upload them to Algolia. For example:
41+
To build all the indices without uploading them to Algolia's servers (this takes about an hour):
3442
```
35-
VERSION='free-pro-team@latest' LANGUAGE='en' npm run sync-search-dry-run
43+
npm run sync-search-dry-run
3644
```
37-
Or you can build and load them to Algolia to make them live:
45+
To build indices for a specific language and/or version (this is much faster):
3846
```
39-
VERSION='free-pro-team@latest' LANGUAGE='en' npm run sync-search
47+
VERSION=<PLAN@RELEASE> LANGUAGE=<TWO-LETTER CODE> npm run sync-search-dry-run
4048
```
41-
The `VERSION` environment variable must be a currently supported version in `<PLAN@RELEASE>` format. The `LANGUAGE` environment variable must be a currently supported two-letter language code.
49+
You can set `VERSION` and `LANGUAGE` individually, too.
4250

43-
### Label-triggered workflow
51+
Substitute a currently supported version for `<PLAN@RELEASE>` and a currently supported two-letter language code for `<TWO-LETTER-CODE>`.
4452

45-
For our daily shipping needs, the indices are synced to Algolia only after a PR is shipped to the default branch, which means the search data isn't available for up to an hour after the content goes live.
53+
### Build and sync
4654

47-
But for GHES releases, we have additional needs. We want:
55+
To build all the indices and sync them to Algolia (this also takes about an hour):
56+
```
57+
npm run sync-search
58+
```
59+
To build indices for a specific language and/or version and sync them to Algolia:
60+
```
61+
VERSION=<PLAN@RELEASE LANGUAGE=<TWO-LETTER CODE> npm run sync-search
62+
```
63+
You can set `VERSION` and `LANGUAGE` individually, too.
4864

49-
1) The search results to be live immediately upon releasing the new content.
50-
2) The search results to be viewable on the staging app for the GHES release megabranch.
65+
Substitute a currently supported version for `<PLAN@RELEASE>` and a currently supported two-letter language code for `<TWO-LETTER-CODE>`.
5166

52-
Manually running `npm run sync` locally before shipping the megabranch can address #1, but it's cumbersome and hard to get the timing right. And it does not address #2.
67+
## Label-triggered workflow
5368

54-
Now, docs team members can use an Actions workflow on GHES megabranch PRs by applying a label in this format:
69+
Docs team members can use an Actions workflow on GHES release PRs by applying a label in this format:
5570
```
5671
sync-english-index-for-<PLAN@RELEASE>
5772
```
58-
This label will run a workflow on every push to **build and upload ONLY** the English index for the specified version. This means:
73+
This label will run a workflow on every push that **builds and uploads ONLY** the English index for the specified version. This means:
5974

60-
* The GHES content will be searchable at the same time the megabranch is shipped, with no delay.
75+
* The GHES content will be searchable at the same time the release PR is shipped, with no delay.
6176
* The GHES content will be searchable on staging throughout content creation.
62-
* No manual steps (unless anyone wants to do a dry-run test as described in the previous section).
77+
* No manual steps (unless you want to do a [dry run test](#build-without-sync-dry-run)).
78+
79+
Why do we need this? For our daily shipping needs, it's tolerable that search updates aren't available for up to an hour after the content goes live. But GHES releases are more time-sensitive, and writers have a greater need to preview search data on staging.
6380

6481
## Files
6582

66-
- [.github/workflows/sync-algolia-search-indices.yml](.github/workflows/sync-algolia-search-indices.yml) - the GitHub Actions workflow file that updates search indices whenever the main branch is updated.
67-
- [javascripts/search.js](javascripts/search.js) - the browser-side code that enables search using Algolia's [InstantSearch.js](https://github.com/algolia/instantsearch.js/) library.
68-
- [lib/algolia/client.js](lib/algolia/client.js) - a thin wrapper around the [algoliasearch](https://ghub.io/algoliasearch) Node.js module for interacting with the Algolia API.
69-
- [lib/algolia/search-index.js](lib/algolia/search-index.js) - a class for generating structured search data from repository content and syncing it with the remote Algolia service. This class has built-in validation to ensure that all records are valid before they're uploaded. This class also takes care of removing deprecated records, and compares existing remote records with the latest local records to avoid uploading records that haven't changed.
70-
- [script/sync-algolia-search-indices.js](script/sync-algolia-search-indices.js) - the script used by the Actions workflow to update search indices on our Algolia account. This can also be [run in the development environment](#development).
71-
- [tests/algolia-search.js](tests/algolia-search.js) - tests!
83+
### GitHub Actions workflow files
84+
85+
- [`.github/workflows/sync-algolia-search-indices.yml`](.github/workflows/sync-algolia-search-indices.yml) - Builds and syncs search indices whenever the `main` branch is pushed to (that is, on production deploys).
86+
- [`.github/workflows/dry-run-sync-algolia-search-indices.yml`](.github/workflows/dry-run-sync-algolia-search-indices.yml) - This workflow can be run manually (via `workflow_dispatch`) to do a dry run build of all the indices. Useful for confirming that the indices can build without erroring out.
87+
- [`.github/workflows/sync-single-english-algolia-index.yml`](.github/workflows/sync-single-english-algolia-index.yml) - This workflow is run when a label in the right format is applied to a PR. See "[Label-triggered workflow](#label-triggered-workflow)" for details.
88+
89+
### Code files
90+
91+
- [javascripts/search.js](javascripts/search.js) - The browser-side code that enables search using Algolia's [InstantSearch.js](https://github.com/algolia/instantsearch.js/) library.
92+
- [lib/algolia/client.js](lib/algolia/client.js) - A thin wrapper around the [algoliasearch](https://ghub.io/algoliasearch) Node.js module for interacting with the Algolia API.
93+
- [lib/algolia/search-index.js](lib/algolia/search-index.js) - A class for generating structured search data from repository content and syncing it with the remote Algolia service. This class has built-in validation to ensure that all records are valid before they're uploaded. This class also takes care of removing deprecated records, and compares existing remote records with the latest local records to avoid uploading records that haven't changed.
94+
- [script/sync-algolia-search-indices.js](script/sync-algolia-search-indices.js) - The script used by the Actions workflow to update search indices on our Algolia account. This can also be [run in the development environment](#development).
95+
- [tests/algolia-search.js](tests/algolia-search.js) - Tests!
7296

7397
## Indices
7498

0 commit comments

Comments
 (0)