Update for review feedback

felicitymay · felicitymay · commit b21253732b48 · 2023-02-28T09:58:51.000Z
diff --git a/docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst b/docs/codeql/codeql-for-visual-studio-code/customizing-settings.rst
@@ -73,7 +73,7 @@ You can define or edit lists of GitHub repositories for variant analysis, and ch
 
 For information on the purpose and requirements for a controller repository, see ":ref:`Setting up a controller repository for variant analysis <controller-repository>`."
 
-You can also edit the items shown in the Variant analysis repositories panel by editing a file in your Visual Studio Code workspace called ``databases.json``. This file contains a JSON representation of all the items displayed in the panel. To open your ``databases.json`` file in an editor window, click the **{ }** icon in the top right of the variant analysis repositories panel. You can then see a structured representation of the repos, orgs and lists in your panel. For example:
+You can also edit the items shown in the Variant Analysis Repositories panel by editing a file in your Visual Studio Code workspace called ``databases.json``. This file contains a JSON representation of all the items displayed in the panel. To open your ``databases.json`` file in an editor window, click the **{ }** icon in the top right of the Variant Analysis Repositories panel. You can then see a structured representation of the repos, orgs and lists in your panel. For example:
 
 .. code-block:: json
 
@@ -83,7 +83,7 @@ You can also edit the items shown in the Variant analysis repositories panel by
       "variantAnalysis": {
         "repositoryLists": [
           {
-            "name": "My favourite JavaScript repos",
+            "name": "My favorite JavaScript repos",
             "repositories": [
               "facebook/react",
               "babel/babel",
diff --git a/docs/codeql/codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.rst b/docs/codeql/codeql-for-visual-studio-code/exploring-data-flow-with-path-queries.rst
@@ -30,7 +30,7 @@ Running path queries in VS Code locally
 #. Click each step to jump to it in the source code and investigate the problem further.
 #. To navigate the results from your keyboard, you can bind shortcuts to the **CodeQL: Navigate Up/Down/Left/Right in Result Viewer** commands.
 
-When you are ready to run a path query at scale, you can use the Variant Analysis Repositories panel to run the query against up to 1000 repositories on GitHub.com. For information on running analysis at scale across many CodeQL databases, see ":ref:`Running CodeQL queries at scale with multi-repository variant analysis <running-codeql-queries-at-scale-with-mrva>`."
+When you are ready to run a path query at scale, you can use the Variant Analysis Repositories panel to run the query against up to 1,000 repositories on GitHub.com. For information on running analysis at scale across many CodeQL databases, see ":ref:`Running CodeQL queries at scale with multi-repository variant analysis <running-codeql-queries-at-scale-with-mrva>`."
 
 Further reading
 -----------------
diff --git a/docs/codeql/codeql-for-visual-studio-code/running-codeql-queries-at-scale-with-mrva.rst b/docs/codeql/codeql-for-visual-studio-code/running-codeql-queries-at-scale-with-mrva.rst
@@ -14,7 +14,9 @@ When you write a query to find variants of a security vulnerability and finish t
 
 The core functionality of the CodeQL extension helps you write queries and run them locally against a CodeQL database. In contrast, variant analysis allows you to send your CodeQL query to GitHub.com to be tested against a list of repositories.
 
-When you run variant analysis against a list of repositories, your query is run against each repository that has a CodeQL database available to analyze. GitHub creates and stores CodeQL databases for thousands of public repositories, including every repository that runs code scanning using CodeQL. If you want to run variant analysis on your repositories, you need to enable code scanning using CodeQL on GitHub.com before adding your repository to a list for analysis (either default setup, or advanced setup using the CodeQL action). For information about enabling code scanning using CodeQL, see "`Configuring code scanning automatically <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically>`__."
+When you run variant analysis against a list of repositories, your query is run against each repository that has a CodeQL database available to analyze. GitHub creates and stores the latest CodeQL database for the default branch of thousands of public repositories, including every repository that runs code scanning using CodeQL. 
+
+If you want to run variant analysis on your repositories, you need to enable code scanning using CodeQL on GitHub.com before adding your repository to a list for analysis (either default setup, or advanced setup using the CodeQL action). For information about enabling code scanning using CodeQL, see "`Configuring code scanning automatically <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically>`__."
 
 .. _controller-repository:
 
@@ -42,23 +44,20 @@ You must define a controller repository before you can run your first variant an
 
 #. Type the owner and name of the repository on GitHub.com that you want to use as your controller repository and press the **Enter** key.
 
-#. If you are prompted to authenticate with GitHub, follow the instructions and sign into your pesonal or organization account. When you have finished following the process, a prompt from GitHub Authentication may ask for permission to open a URI in Visual Studio Code, click **Open**.
+#. If you are prompted to authenticate with GitHub, follow the instructions and sign into your personal or organization account. When you have finished following the process, a prompt from GitHub Authentication may ask for permission to open a URI in Visual Studio Code, click **Open**.
 
 The name of the controller repository is saved in your settings for the CodeQL extension. For information on how to edit the controller repository, see ":ref:`Customizing settings <customizing-settings>`."
 
 Running a query at scale using variant analysis
 -----------------------------------------------
 
-#. Expand the **Variant Analysis Repositories** section, to show the default lists of the top 10, top 100, and top 1000 public repositories on GitHub.com. These are ranked by considering various metrics such as number of stars, number of watchers, number of forks etc.
+#. Expand the **Variant Analysis Repositories** section, to show the default lists of the top 10, top 100, and top 1,000 public repositories on GitHub.com. These are ranked by considering various metrics such as number of stars, number of watchers, number of forks etc.
 
-#. Select which GitHub repository or repositories you want to run your query against.
+#. Select which GitHub repository or repositories you want to run your query against. Click a row to highlight it, and then click **Select** to select that repository, organization, or list of repositories. If you want to add a new repository, organization, or list, use the options in the header panel. For information, see ":ref:`Creating custom lists of repositories <custom-lists>`", later in this article.
 
-   - Click **Top X repositories** to select this list of public repositories for analysis.
-   - Click **LIST-NAME** to select a custom list for analysis (see :ref:`later in this article <custom-lists>` for details).
-   - Click **Add new database**, the **+** icon, to add a repository or an organization to the panel, then click to select it for analysis.
-        .. image:: ../images/codeql-for-visual-studio-code/variant-analysis-repo-lists.png
-            :width: 350
-            :alt: Screenshot of the CodeQL extension in Visual Studio Code. The "Variant Analysis Repositories" section is expanded. The "Top 10 repositories" item has a checkmark to show that it is currently selected. Examples of a custom list, "example-list", a full organization, "octo-org", and a single repository, "octo-org/octo-repo", are shown in the list of repositories available for variant analysis.
+    .. image:: ../images/codeql-for-visual-studio-code/variant-analysis-repo-lists.png
+        :width: 350
+        :alt: Screenshot of the CodeQL extension in Visual Studio Code. The "Variant Analysis Repositories" section is expanded. The "Top 10 repositories" item has a checkmark to show that it is currently selected for analysis. The user has clicked on the row for a single repository "octo-org/octo-repo" and it is highlighted blue. The "Select" button for that row is highlighted with a dark orange highlight.
 
 #. Open the query you want to run, right-click in the query file, and select **CodeQL: Run Variant Analysis** to start variant analysis.
 
@@ -73,7 +72,7 @@ The CodeQL extension builds a CodeQL pack with your library and any library depe
 Exploring your results
 ----------------------
 
-When you run variant analysis, as soon as a workflow to run your analysis on GitHub is running, a Variant Analysis Results view opens to display the results as soon as they are ready. You can use this view to monitor progress, see any errors, and access the workflow logs in your controller repository.
+When you run variant analysis, as soon as a workflow to run your analysis on GitHub is running, a Variant Analysis Results view opens to display the results as they are ready. You can use this view to monitor progress, see any errors, and access the workflow logs in your controller repository.
 
 .. image:: ../images/codeql-for-visual-studio-code/variant-analysis-results-view.png
     :alt: Screenshot of the "Variant Analysis Results" view showing a partially complete run. Analysis of ``angular/angular`` is still running but all other results are displayed. ``facebook/create-react-app`` has three results for this query.
@@ -113,7 +112,7 @@ After you have defined a controller repository, the Variant Analysis Repositorie
 
     Note
 
-    CodeQL analysis always requires a CodeQL database to run queries against. When you run variant analysis against a list of repositories, your query will only be executed against the repositories that currently have a CodeQL database available to download.  So the best way to make a repository available for variant analysis is to enable code scanning with CodeQL. For information about enabling code scanning using CodeQL, see "`Configuring code scanning automatically <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically>`__."
+    CodeQL analysis always requires a CodeQL database to run queries against. When you run variant analysis against a list of repositories, your query will only be executed against the repositories that currently have a CodeQL database available to download.  The best way to make a repository available for variant analysis is to enable code scanning with CodeQL. For information about enabling code scanning using CodeQL, see "`Configuring code scanning automatically <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically>`__."
 
 Selecting a single GitHub repository or organization for analysis
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/codeql/codeql-for-visual-studio-code/troubleshooting-codeql-for-visual-studio-code.rst b/docs/codeql/codeql-for-visual-studio-code/troubleshooting-codeql-for-visual-studio-code.rst
@@ -6,11 +6,11 @@ Troubleshooting CodeQL for Visual Studio Code
 =============================================
 
 This article explains how to debug problems with the analysis of CodeQL databases that are stored on your local
-machine. For information on troubleshooting variant analysis, where the analysis is run using GitHub Actions, see
+machine. For information on troubleshooting variant analysis, which runs on GitHub.com, see
 ":ref:`Troubleshooting variant analysis <troubleshooting-variant-analysis>`."
 
 You can use the detailed information written to the extension's log files if you need to troubleshoot problems
-analysing CodeQL databases that are stored locally.
+analyzing CodeQL databases that are stored locally.
 
 About the log files
 --------------------
diff --git a/docs/codeql/codeql-for-visual-studio-code/troubleshooting-variant-analysis.rst b/docs/codeql/codeql-for-visual-studio-code/troubleshooting-variant-analysis.rst
@@ -7,7 +7,7 @@ Troubleshooting variant analysis
 
 .. include:: ../reusables/beta-note-mrva.rst
 
-This article explains how to debug problems with variant analysis. That is, analysis run using GitHub Actions
+This article explains how to debug problems with variant analysis, that is, analysis run using GitHub Actions
 and not locally on your machine.
 For information on troubleshooting local analysis, see
 ":ref:`Troubleshooting CodeQL for Visual Studio Code <troubleshooting-codeql-for-visual-studio-code>`."
@@ -26,5 +26,5 @@ If there are problems with the variant analysis run, you will see a warning bann
     :width: 600
     :alt: Screenshot of the "Variant Analysis Results" view showing a warning banner with the text "warning: Problem with controller repository" and "Publicly visible controller repository can't be used to analyze private repositories. 1 private repository was not analyzed." The "Show logs" button is highlighted with a dark orange outline.
 
-In this example, the user ran variant analysis on a custom list of two repositories. One of the repositories was a private repository and could not be analyzed because they had a public controller repository. Only the public repository was analyzed. To analyze both repositories, they need to edit their settings and update the controller repository to a private repository. For information on how to edit the controller repository, see ":ref:`Customizing settings <customizing-settings>`."
+In this example, the user ran variant analysis on a custom list of two repositories. One of the repositories was a private repository and could not be analyzed because they had a public controller repository. Only the public repository was analyzed. To analyze both repositories, this user needs to edit their settings and update the controller repository to a private repository. For information on how to edit the controller repository, see ":ref:`Customizing settings <customizing-settings>`."
 
diff --git a/docs/codeql/images/codeql-for-visual-studio-code/variant-analysis-repo-lists.png b/docs/codeql/images/codeql-for-visual-studio-code/variant-analysis-repo-lists.png
diff --git a/docs/codeql/reusables/beta-note-mrva.rst b/docs/codeql/reusables/beta-note-mrva.rst
@@ -2,6 +2,6 @@
 
     Note
 
-    Multi-repository variant analysis is currently available as a beta release and is subject to change. To use this feature you must upgrade the CodeQL extension for Visual Studio Code to a minimum of version 1.8.0.
+    Multi-repository variant analysis is currently available as a beta release and is subject to change. To use this feature, you must upgrade the CodeQL extension for Visual Studio Code to a minimum of version 1.8.0.
     
     To provide feedback on the feature, see TODO-community-feedback-link.
