Merge pull request #7571 from github/aeisenberg/remove-upgrades

Update docs on the output of `resolve qlpacks`

Author: aeisenberg

docs/codeql/codeql-cli/getting-started-with-the-codeql-cli.rst

@@ -4,7 +4,7 @@ Getting started with the CodeQL CLI
 ===================================
 
 To run CodeQL commands, you need to set up the CLI so that it can access
-the tools, queries, and libraries required to create and analyze databases. 
+the tools, queries, and libraries required to create and analyze databases.
 
 .. include:: ../reusables/license-note.rst
 
@@ -18,16 +18,16 @@ structures. To get started quickly, we recommend adopting a relatively simple
 setup, as outlined in the steps below.
 
 If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
-follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1 
-and 4 are slightly different---for further details, see the sections labeled 
+follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
+and 4 are slightly different---for further details, see the sections labeled
 **Information for macOS "Catalina" (or newer) users**. If you are using macOS
 on Apple Silicon (e.g. Apple M1), ensure that the `Xcode command-line developer
 tools <https://developer.apple.com/downloads/index.action>`__ and `Rosetta 2
 <https://support.apple.com/en-us/HT211861>`__ are installed.
 
 For information about installing the CodeQL CLI in a CI system to create results
-to display in GitHub as code scanning alerts, see 
-`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__ 
+to display in GitHub as code scanning alerts, see
+`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
 in the GitHub documentation.
 
 1. Download the CodeQL CLI zip package
@@ -42,9 +42,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
 
    There are several different versions of the CLI available to download, depending
    on your use case:
-   
+
    - If you want to use the most up to date CodeQL tools and features, download the
-     version tagged ``latest``. 
+     version tagged ``latest``.
 
    - If you want to create CodeQL databases to upload to LGTM Enterprise, download
      the version that is compatible with the relevant LGTM Enterprise version
@@ -53,9 +53,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
      <https://github.com/github/codeql-cli-binaries/releases>`__ on GitHub. Using the
      correct version of the CLI ensures that your CodeQL databases are
      compatible with your version of LGTM Enterprise. For more information,
-     see `Preparing CodeQL databases to upload to LGTM 
+     see `Preparing CodeQL databases to upload to LGTM
      <https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
-     in the LGTM admin help. 
+     in the LGTM admin help.
 
 If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
 `download the zip archive
@@ -72,12 +72,12 @@ Alternatively, you can download ``codeql.zip``, which contains the CLI for all s
       **Information for macOS "Catalina" (or newer) users**
 
    .. pull-quote:: macOS "Catalina" (or newer)
-      
-      If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming 
-      version 12 ("Monterey"), you need to ensure that your web browser does not automatically 
-      extract zip files. If you use Safari, complete the following steps before downloading 
+
+      If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
+      version 12 ("Monterey"), you need to ensure that your web browser does not automatically
+      extract zip files. If you use Safari, complete the following steps before downloading
       the CodeQL CLI zip archive:
-          
+
       i. Open Safari.
       ii. From the Safari menu, select **Preferences...**.
       iii. Click the **General** Tab.
@@ -101,22 +101,22 @@ further options on the command line.
 3. Obtain a local copy of the CodeQL queries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The `CodeQL repository <https://github.com/github/codeql>`__ contains 
+The `CodeQL repository <https://github.com/github/codeql>`__ contains
 the queries and libraries required for CodeQL analysis of C/C++, C#, Java,
 JavaScript/TypeScript, Python, and Ruby.
-Clone a copy of this repository into ``codeql-home``. 
- 
-By default, the root of the cloned repository will be called ``codeql``. 
-Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL 
-CLI that you will extract in step 4. If you use git on the command line, you can 
-clone and rename the repository in a single step by running 
+Clone a copy of this repository into ``codeql-home``.
+
+By default, the root of the cloned repository will be called ``codeql``.
+Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL
+CLI that you will extract in step 4. If you use git on the command line, you can
+clone and rename the repository in a single step by running
 ``git clone git@github.com:github/codeql.git codeql-repo`` in the ``codeql-home`` folder.
 
 The CodeQL libraries and queries for Go analysis live in the `CodeQL for Go
 repository <https://github.com/github/codeql-go/>`__. Clone a copy of this
-repository into ``codeql-home``. 
+repository into ``codeql-home``.
 
-The cloned repositories should have a sibling relationship. 
+The cloned repositories should have a sibling relationship.
 For example, if the root of the cloned CodeQL repository is
 ``$HOME/codeql-home/codeql-repo``, then the root of the cloned CodeQL for Go
 repository should be ``$HOME/codeql-home/codeql-go``.
@@ -134,29 +134,29 @@ see ":doc:`About QL packs <about-ql-packs>`."
    - For the queries used on `LGTM.com <https://lgtm.com>`__, check out the
      ``lgtm.com`` branch. You should use this branch for databases you've built
      using the CodeQL CLI, fetched from code scanning on GitHub, or recently downloaded from LGTM.com.
-     The queries on the ``lgtm.com`` branch are more likely to be compatible 
-     with the ``latest`` CLI, so you'll be less likely to have to upgrade 
-     newly-created databases than if you use the ``main`` branch. Older databases 
+     The queries on the ``lgtm.com`` branch are more likely to be compatible
+     with the ``latest`` CLI, so you'll be less likely to have to upgrade
+     newly-created databases than if you use the ``main`` branch. Older databases
      may need to be upgraded before you can analyze them.
-   
-   - For the most up to date CodeQL queries, check out the ``main`` branch. 
+
+   - For the most up to date CodeQL queries, check out the ``main`` branch.
      This branch represents the very latest version of CodeQL's analysis. Even
      databases created using the most recent version of the CLI may have to be
      upgraded before you can analyze them. For more information, see
      ":doc:`Upgrading CodeQL databases <upgrading-codeql-databases>`."
-        
+
    - For the queries used in a particular LGTM Enterprise release, check out the
      branch tagged with the relevant release number. For example, the branch
      tagged ``v1.27.0`` corresponds to LGTM Enterprise 1.27. You must use this
      version if you want to upload data to LGTM Enterprise. For further
-     information, see `Preparing CodeQL databases to upload to LGTM 
+     information, see `Preparing CodeQL databases to upload to LGTM
      <https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
      in the LGTM admin help.
 
 4. Extract the zip archive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier) 
+For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
 simply
 extract the zip archive into the directory you created in step 2.
 
@@ -171,16 +171,16 @@ For example, if the path to your copy of the CodeQL repository is
       **Information for macOS "Catalina" (or newer) users**
 
    .. pull-quote:: macOS "Catalina"
-   
-      macOS "Catalina", "Big Sur", or "Monterey" users should run the following 
-      commands in the Terminal, where ``${install_loc}`` is the path to the 
+
+      macOS "Catalina", "Big Sur", or "Monterey" users should run the following
+      commands in the Terminal, where ``${install_loc}`` is the path to the
       directory you created in step 2:
-   
+
       i. ``mv ~/Downloads/codeql*.zip ${install_loc}``
       ii. ``cd ${install_loc}``
       iii. ``/usr/bin/xattr -c codeql*.zip``
       iv. ``unzip codeql*.zip``
-   
+
 5. Launch ``codeql``
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -191,7 +191,7 @@ executable in a couple of ways:
   ``<extraction-root>`` is the folder where you extracted the CodeQL CLI
   package.
 - By adding ``<extraction-root>/codeql`` to your ``PATH``, so that you
-  can run the executable as just ``codeql``. 
+  can run the executable as just ``codeql``.
 
 At this point, you can execute CodeQL commands. For a full list of the CodeQL
 CLI commands, see the "`CodeQL CLI manual <../manual>`__."
@@ -212,16 +212,20 @@ up to create and analyze databases:
 
 - Run ``codeql resolve languages`` to show which languages are
   available for database creation. This will list the languages supported by
-  default in your CodeQL CLI package. 
+  default in your CodeQL CLI package.
 - Run ``codeql resolve qlpacks`` to show which QL packs the CLI can find. This
-  will display the names of the QL packs included in the CodeQL repositories:
-  ``codeql-cpp``, ``codeql-csharp``, ``codeql-go``,
-  ``codeql-java``, ``codeql-javascript``, and ``codeql-python``. The CodeQL
-  repositories also contain 'upgrade' packs and 'legacy' packs. Upgrade packs
-  are used by the CLI when you want to upgrade a database so that it can be
-  analyzed with a newer version of the CodeQL toolchain than was used to create
-  it. Legacy packs ensure that custom queries and libraries created using older
-  products are compatible with your version of CodeQL.
+  will display the names of all the QL packs directly available to the CodeQL CLI.
+  This should include:
+
+  - Query packs for each supported language, for example, ``codeql/{language}-queries``.
+    These packs contain the standard queries that will be run for each analysis.
+  - Library packs for each supported language, for example,  ``codeql/{language}-all``. These
+    packs contain query libraries, such as control flow and data flow libraries, that
+    may be useful to query writers.
+  - Example packs for each supported language, for example, ``codeql/{language}-examples``.
+    These packs contain useful snippets of CodeQL that query writers may find useful.
+  - Legacy packs that ensure custom queries and libraries created using older products are
+    compatible with your version of CodeQL.
 
 
 .. _using-two-versions-of-the-codeql-cli:
@@ -242,4 +246,4 @@ recommended directory setup depends on which versions you want to install:
   directory. For example, if you unpack version 2.0.2 into
   ``$HOME/codeql-home/codeql-cli``, the older version should be
   unpacked into ``$HOME/codeql-older-version/old-codeql-cli``. Here, the common
-  grandparent is the ``$HOME`` directory. 
+  grandparent is the ``$HOME`` directory.