Apply suggestions from code review

felicitymay · web-flow · commit 8b64b8144c1a · 2021-07-26T18:15:04.000+01:00
diff --git a/docs/codeql/codeql-cli/about-codeql-packs.rst b/docs/codeql/codeql-cli/about-codeql-packs.rst
@@ -13,8 +13,8 @@ CodeQL packs are used to create, share, depend on, and run CodeQL queries and li
 
 There are two types of CodeQL packs: query packs and library packs.
 
-* Query packs are designed to be run. They are bundled with all transitive dependencies. Also included in the tarball is a compilation cache which is used to ensure the packs' efficient execution.
-* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included in the final pack.
+* Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and a compilation cache. This ensures consistent and efficient execution of the queries in the pack.
+* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included when the pack is published.
 
 You can use the CodeQL package manger in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. For more information, see ":ref:`Creating and working with CodeQL packs <creating-and-working-with-codeql-packs>`." You can also publish and download CodeQL packs using the CodeQL package manager. For more information, see ":doc:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`."
 
@@ -31,11 +31,11 @@ files and directories within the pack should be logically organized. For example
 About ``qlpack.yml`` files
 --------------------------
 
-When executing query-related commands, CodeQL first looks in the package cache for CodeQL packs which have already been downloaded. If a suitable pack cannot be found, then CodeQL scans siblings of the installation directory (and their subdirectories) for ``qlpack.yml`` files. The metadata in the file tells
-CodeQL how to compile queries, what libraries the pack depends on, and where to
+When executing query-related commands, CodeQL first looks in the package cache for CodeQL packs which have already been downloaded. If a suitable pack cannot be found, then CodeQL scans siblings of the installation directory (and their subdirectories) for ``qlpack.yml`` files. The metadata in each `qlpack.yml`` file tells
+CodeQL how to compile any queries in the pack, what libraries the pack depends on, and where to
 find query suite definitions.
 
-The content of the CodeQL pack (queries and libraries used in CodeQL analysis) is
+The contents of the CodeQL pack (queries or libraries used in CodeQL analysis) is
 included in the same directory as ``qlpack.yml``, or its subdirectories.
 
 The location of ``qlpack.yml`` defines the library path for the content
@@ -61,15 +61,15 @@ The following properties are supported in ``qlpack.yml`` files.
    * - ``name``
      - ``octo-org/security-queries``
      - All packs
-     - The scope, where the CodeQL pack is published, and the name of the pack defined using alphanumeric characters, hyphens, and periods. It must be unique as CodeQL cannot differentiate between CodeQL packs with identical names. Name components cannot start or end with a hyphen. Additionally, a period is not allowed in pack names at all. Use the pack name to specify queries to run using ``database analyze`` and to define dependencies between QL packs (see examples below).
+     - The scope, where the CodeQL pack is published, and the name of the pack defined using alphanumeric characters and hyphens. It must be unique as CodeQL cannot differentiate between CodeQL packs with identical names. Name components cannot start or end with a hyphen. Additionally, a period is not allowed in pack names at all. Use the pack name to specify queries to run using ``database analyze`` and to define dependencies between QL packs (see examples below).
    * - ``version``
      - ``0.0.0``
      - All packs
      - A version number for this CodeQL pack. This must be a valid semantic version that meets the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
    * - ``dependencies``
      - ``codeql/javascript-all: 1.2.3``
      - Optional
-     - The names of any CodeQL packs that this pack depends on, as a sequence. This gives the pack access to any libraries, database schema, and query suites defined in the dependency.
+     - The names of any CodeQL packs that this pack depends on, as a sequence. This gives the pack access to any libraries, database schema, and query suites defined in the dependency. Optionally a version for the dependency is specified. 
    * - ``suites``
      - ``octo-org-query-suites``
      - Optional
@@ -84,7 +84,7 @@ The following properties are supported in ``qlpack.yml`` files.
      - The path to a directory within the pack that contains tests, defined relative to the pack directory. Use ``.`` to specify the whole pack. Any queries in this directory are run as tests when ``test run`` is run with the ``--strict-test-discovery`` option. These queries are ignored by query suite definitions that use ``queries`` or ``qlpack``    instructions to ask for all queries in a particular pack.
    * - ``dbscheme``
      - ``semmlecode.python.dbscheme``
-     - Core language pack only
+     - Core language packs only
      - The path to the :ref:`database schema <codeql-database-schema>` for all libraries and queries written for this CodeQL language (see example below).
    * - ``upgrades``
      - ``.``
diff --git a/docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst b/docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
@@ -115,13 +115,13 @@ Running a CodeQL pack
 
     Note
 
-    The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in GitHub Packages - the GitHub Container Registry (GHCR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
+    The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only using GitHub Packages - the GitHub Container registry. You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
 
-To run an existing CodeQl pack from GitHub Packages - the GitHub Container Registry (GHCR), you need to download it first:
+To run an existing CodeQL query pack from the GitHub Container registry, you need to download it first::
 
    codeql pack download microsoft/coding-standards@1.0.0
 
-Afterwards, you can run the pack on a specific database:
+Afterwards, you can run the pack on a specific database::
 
    codeql database analyze <database> microsoft/coding-standards@1.0.0 <scope>/<other-pack> --format=sarifv2.1.0 --output=query-results.sarif
 
@@ -137,13 +137,13 @@ you could use the following command from the directory containing your database:
    codeql database analyze <cpp-database> cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif
 
 The analysis generates a file in the v2.1.0 SARIF format that is supported by all versions of GitHub.
-This file can be uploaded to GitHub executing ``codeql github upload-results`` or the code scanning API.
+This file can be uploaded to GitHub by executing ``codeql github upload-results`` or the code scanning API.
 For more information, see `Analyzing a CodeQL database <https://docs.github.com/en/code-security/secure-coding/configuring-codeql-cli-in-your-ci-system#analyzing-a-codeql-database>`__
 or `Code scanning API <https://docs.github.com/en/rest/reference/code-scanning>`__ in the GitHub documentation.
 
 CodeQL query suites are ``.qls`` files that use directives to select queries to run
 based on certain metadata properties. The standard QL packs have metadata that specify
-the location of the query suites, so the CodeQL CLI knows where to find these
+the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these
 suite files automatically, and you don't have to specify the full path on the command line.
 For more information, see ":ref:`About QL packs <standard-ql-packs>`."
 
@@ -157,7 +157,7 @@ and at the following path in the CodeQL for Go repository::
    ql/src/codeql-suites/go-code-scanning.qls
 
 The repository also includes the query suites used by `LGTM.com <https://lgtm.com>`__.
-These are stored alongside the query suites with names of the form: ``<language>-lgtm.qls``.
+These are stored alongside the query suites for code scanning with names of the form: ``<language>-lgtm.qls``.
 
 For information about creating custom query suites, see ":doc:`Creating
 CodeQL query suites <creating-codeql-query-suites>`."
@@ -169,46 +169,18 @@ When you create a CodeQL database, the extractor stores diagnostic data in the d
 
 If the analysis found fewer results for standard queries than you expected, review the results of the diagnostic and summary queries to check whether the CodeQL database is likely to be a good representation of the codebase that you want to analyze.
 
-Integrating a CodeQL pack into a Code Scanning workflow
+Integrating a CodeQL pack into a code scanning workflow in GitHub
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. pull-quote::
 
     Note
 
-    The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in GitHub Packages - the GitHub Container Registry (GHCR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
+    The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only using GitHub Packages - the GitHub Container registry. You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
 
-Using packs inside your Code Scanning setup allows selecting query packs from various sources.
+You can use CodeQL query packs in your Code Scanning setup. This allows you to select query packs published by various sources and use them to analyze your code. 
+For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
 
-In the CodeQL configuration file, the section called ``packs`` holds a list of CodeQL package references. Each package listed there will be downloaded by the action and the its default suite will be run.
-
-   queries:
-     - queries/query1.ql
-     - queries/suite1.qls
-   packs:
-     - codeql/pack1@~1.2.3  # latest version compatible with 1.2.3
-     - codeql/pack2         # latest version
-
-For multi-language runs, you can specify a nested map of packs:
-
-   packs:
-     javascript:
-       - codeql/js-pack1@~1.2.3
-       - codeql/js-pack2
-     java:
-       - codeql/java-pack1@~1.2.3
-       - codeql/java-pack2
-
-In the CodeQL workflow file, you can add ``packs`` as input for the ``init`` action by using a comma-separated list of CodeQL packages and optional versions.
-
-.. code-block:: none
-
-   uses: github/codeql-action@v1
-   with:
-     packs: codeql/pack1@~1.2.3, +codeql/pack2
-
-This format does not support multi-language analyses.
-You can prefix a package reference with a plus sign, resulting in the input being combined with the config file. Without it, the input overwrites the config file.
 
 Running all queries in a directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst b/docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst
@@ -9,23 +9,23 @@ You can use CodeQL packs to create, share, depend on, and run CodeQL queries and
 
    Note
 
-   The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in the GitHub Package Registry (GHPR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
+   The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only using GitHub Packages - the GitHub Container registry. You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
 
 About CodeQL packs and the CodeQL CLI package manager
 -----------------------------------------------------
 
-With CodeQL packs and the CodeQL CLI package manager, you can publish your custom queries and integrate them into your CodeQL code scanning workflow to run and analyze your codebase.
+With CodeQL packs and the CodeQL CLI package manager, you can publish your custom queries and integrate them into your codebase analysis.
 
 There are two types of CodeQL packs: query packs and library packs.
 
-* Query packs are designed to be run. The query packs are bundled with all transitive dependencies and a compilation cache is included in the tarball.
-* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included in the final pack.
+* Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and a compilation cache. This ensures consistent and efficient execution of the queries in the pack.
+* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled and there is no compilation cache included when the pack is published.
 
 You can use the CodeQL package manger in the CodeQL CLI to create CodeQL packs, add dependencies to packs, and install or update dependencies. You can also publish and download CodeQL packs using the CodeQL package manager. For more information, see ":doc:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`."
 
-Running ``codeql pack init``
+Creating a CodeQL pack
 ----------------------------
-You can create CodeQL packs are by running the following command from the checkout root of your project:
+You can create a CodeQL pack by running the following command from the checkout root of your project:
 
 ::
 
@@ -40,10 +40,12 @@ The ``codeql pack init`` command creates the directory structure and configurati
 
 Modifying an existing QL pack to create a CodeQL pack
 -----------------------------------------------------
-If you already have a ``qlpack.yml`` file, you can edit it manually to be a CodeQL pack.
+If you already have a ``qlpack.yml`` file, you can edit it manually to convert it into a CodeQL pack.
 
-#. Edit the name so that it matches the format ``<scope>/<name>``, where ``<scope>`` is the name of the GitHub organization that you will publish to.
-#. In the ``qlpack.yml`` file, include a version property with a semver identifier, as well as an optional dependencies block.
+#. Edit the ``name`` property so that it matches the format ``<scope>/<name>``, where ``<scope>`` is the name of the GitHub organization that you will publish to.
+#. In the ``qlpack.yml`` file, include a ``version`` property with a semver identifier, as well as an optional ``dependencies`` block.
+
+For more information about the properties, see ":ref:`About CodeQL packs <about-codeql-packs>`."
 
 Adding and installing dependencies to a CodeQL pack
 ---------------------------------------------------
@@ -69,4 +71,4 @@ This command downloads all dependencies to the shared cache on the local disk.
 
    Note
 
-   Running the ``codeql pack add`` and ``codeql pack install`` commands will generate or update the ``qlpack.lock.yml`` file. This file should be checked-in to version control. ``qlpack.lock.yml`` contains the precise version numbers used by the pack.
+   Running the ``codeql pack add`` and ``codeql pack install`` commands will generate or update the ``qlpack.lock.yml`` file. This file should be checked-in to version control. The ``qlpack.lock.yml`` file contains the precise version numbers used by the pack.
diff --git a/docs/codeql/codeql-cli/publishing-and-using-codeql-packs.rst b/docs/codeql/codeql-cli/publishing-and-using-codeql-packs.rst
@@ -9,7 +9,7 @@ You can publish your own CodeQL packs and use packs published by other people.
 
    Note
 
-   The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only in GitHub Packages - the GitHub Container Registry (GHCR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
+   The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only using GitHub Packages - the GitHub Container registry. You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
 
 Configuring the ``qlpack.yml`` file before publishing
 -----------------------------------------------------
@@ -20,27 +20,27 @@ You can check and modify the configuration details of your CodeQL pack prior to
 
    library: # set to true if the pack is a library. Set to false or omit for a query pack
    name: <scope>/<pack>
-   version: x.x.x
-   description:
+   version: <x.x.x>
+   description: <Description to publish with the package>
    default-suite: # a query-suite file that has been inlined
        - query:
    default-suite-file: default-queries.qls # a pointer to a query-suite in this pack
-   license:
+   license: # optional, the license under which the pack is published
    dependencies:
 
 - ``name:`` must follow the <scope>/<pack> format, where <scope> is the GitHub organization that you will publish to and <pack> is the name for the pack.
-- Only one of ``default-suite`` or ``default-suite-file`` is allowed. Both options define a default query suite to be run.
+- Only one of ``default-suite`` or ``default-suite-file`` is allowed. Both options define a default query suite to be run, the first by specifying queries directly in the `qlpack.yml` file and the second by specifying a query suite in the pack.
 
 Running ``codeql pack publish``
 -------------------------------
 
-When you are ready to upload a pack to a shared repository, you can run the following command in the root of the pack directory:
+When you are ready to publish a pack to the GitHub Container registry, you can run the following command in the root of the pack directory:
 
 ::
 
   codeql pack publish
 
-The published package will appear in the packages section of your GitHub organization.
+The published package will be displayed in the packages section of GitHub organization specified by the scope in the ``qlpack.yml`` file.
 
 Running ``codeql pack download <scope>/<pack>``
 -----------------------------------------------
diff --git a/docs/codeql/codeql-cli/using-custom-queries-with-the-codeql-cli.rst b/docs/codeql/codeql-cli/using-custom-queries-with-the-codeql-cli.rst
@@ -56,12 +56,11 @@ Packaging custom QL queries
 
     Note
 
-    The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packages are available only in GitHub Packages - the GitHub Container Registry (GHCR). You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
+    The CodeQL package manager is currently in beta and subject to change. During the beta, CodeQL packs are available only using GitHub Packages - the GitHub Container registry. You must use version 2.5.8 or later of the CodeQL CLI to use the CodeQL package manager.
 
 
-When writing your own queries, you can either just save them in a custom QL pack
-directory or subsequently include the pack in a CodeQL package which you can
-then upload to GitHub Packages - the GitHub Container Registry (GHCR).
+When you write your own queries, you should save them in a custom QL pack
+directory. When you are ready to share your queries with other users, you can publish the pack as a CodeQL pack to GitHub Packages - the GitHub Container registry.
 
 QL packs organize the files used in CodeQL analysis and can store queries,
 library files, query suites, and important metadata. Their root directory must
