Merge pull request #11813 from github/rc/3.8

Merge docs updates from rc/3.8 into main

Author: jf205

docs/codeql/reusables/codespaces-template-note.rst

@@ -0,0 +1,8 @@
+.. pull-quote::
+
+   Note
+
+   You can use the CodeQL template (beta) in `GitHub Codespaces <https://github.com/codespaces/new?template_repository=github/codespaces-codeql>`__ to try out the QL concepts and programming-language-agnostic examples in these tutorials. The template includes a guided introduction to working with QL, and makes it easy to get started.
+   
+   When you're ready to run CodeQL queries on actual codebases, you will need to install the CodeQL extension in Visual Studio Code. For instructions, see ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."
+   

docs/codeql/writing-codeql-queries/find-the-thief.rst

@@ -50,7 +50,7 @@ You start asking some creative questions and making notes of the answers so you
 
 There is too much information to search through by hand, so you decide to use your newly acquired QL skills to help you with your investigation...
 
-.. include:: ../reusables/setup-to-run-tutorials.rst
+.. include:: ../reusables/codespaces-template-note.rst
 
 QL libraries
 ------------

docs/codeql/writing-codeql-queries/introduction-to-ql.rst

@@ -14,17 +14,17 @@ QL is a logic programming language, so it is built up of logical formulas. QL us
 
 QL also supports recursion and aggregates. This allows you to write complex recursive queries using simple QL syntax and directly use aggregates such as ``count``, ``sum``, and ``average``.
 
+.. include:: ../reusables/codespaces-template-note.rst
+
 Running a query
 ---------------
 
-You can try out the following examples and exercises using :ref:`CodeQL for VS Code <codeql-for-visual-studio-code>`, or you can run them in the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query on LGTM.com, you need to select a language and project to query (for these logic examples, any language and project will do).
+You can try out the following examples and exercises using :ref:`CodeQL for VS Code <codeql-for-visual-studio-code>` or the `CodeQL template <https://github.com/codespaces/new?template_repository=github/codespaces-codeql>`__ on GitHub Codespaces.
 
-Once you have selected a language, the query console is populated with the query:
+Here is an example of a basic query:
 
 .. code-block:: ql
 
-   import <language>
-
    select "hello world"
 
 This query returns the string ``"hello world"``.
@@ -52,39 +52,33 @@ Simple exercises
 
 You can write simple queries using the some of the basic functions that are available for the ``int``, ``date``, ``float``, ``boolean`` and ``string`` types. To apply a function, append it to the argument. For example, ``1.toString()`` converts the value ``1`` to a string. Notice that as you start typing a function, a pop-up is displayed making it easy to select the function that you want. Also note that you can apply multiple functions in succession. For example, ``100.log().sqrt()`` first takes the natural logarithm of 100 and then computes the square root of the result.
 
-Exercise 1
-~~~~~~~~~~
+Exercise 1 - Strings
+~~~~~~~~~~~~~~~~~~~~
 
 Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
 
-➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2103060623/>`__
+➤ `Check your answer <#exercise-1>`__
 
-There is often more than one way to define a query. For example, we can also write the above query in the shorter form:
-
-.. code-block:: ql
-
-   select "lgtm".length()
-
-Exercise 2
-~~~~~~~~~~
+Exercise 2 - Numbers
+~~~~~~~~~~~~~~~~~~~~
 
 Write a query which returns the sine of the minimum of ``3^5`` (``3`` raised to the power ``5``) and ``245.6``.
 
-➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2093780343/>`__
+➤ `Check your answer <#exercise-2>`__
 
-Exercise 3
-~~~~~~~~~~
+Exercise 3 - Booleans
+~~~~~~~~~~~~~~~~~~~~~
 
 Write a query which returns the opposite of the boolean ``false``.
 
-➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2093780344/>`__
+➤ `Check your answer <#exercise-3>`__
 
-Exercise 4
-~~~~~~~~~~
+Exercise 4 - Dates
+~~~~~~~~~~~~~~~~~~
 
 Write a query which computes the number of days between June 10 and September 28, 2017.
 
-➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2100260596/>`__
+➤ `Check your answer <#exercise-4>`__
 
 Example query with multiple results
 -----------------------------------
@@ -98,8 +92,6 @@ The exercises above all show queries with exactly one result, but in fact many q
          x*x + y*y = z*z
    select x, y, z
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2100790036/>`__
-
 To simplify the query, we can introduce a class ``SmallInt`` representing the integers between 1 and 10. We can also define a predicate ``square()`` on integers in that class. Defining classes and predicates in this way makes it easy to reuse code without having to repeat it every time.
 
 .. code-block:: ql
@@ -113,17 +105,17 @@ To simplify the query, we can introduce a class ``SmallInt`` representing the in
    where x.square() + y.square() = z.square()
    select x, y, z
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2101340747/>`__
-
 Example CodeQL queries
 ----------------------
 
 The previous examples used the primitive types built in to QL. Although we chose a project to query, we didn't use the information in that project's database.
-The following example queries *do* use these databases and give you an idea of how to use CodeQL to analyze projects.
+The following example queries *do* use these databases and give you an idea of how to use CodeQL to analyze projects. 
 
 Queries using the CodeQL libraries can find errors and uncover variants of important security vulnerabilities in codebases.
 Visit `GitHub Security Lab <https://securitylab.github.com/>`__ to read about examples of vulnerabilities that we have recently found in open source projects.
 
+Before you can run the following examples, you will need to install the CodeQL extension for Visual Studio Code. For more information, see :ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`. You will also need to import and select a database in the corresponding programming language. For more information about obtaining CodeQL databases, see `Analyzing your projects <https://codeql.github.com/docs/codeql-for-visual-studio-code/analyzing-your-projects/#choosing-a-database>`__ in the CodeQL for VS Code documentation.
+
 To import the CodeQL library for a specific programming language, type ``import <language>`` at the start of the query.
 
 .. code-block:: ql
@@ -134,7 +126,7 @@ To import the CodeQL library for a specific programming language, type ``import
    where count(f.getAnArg()) > 7
    select f
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2096810474/>`__. The ``from`` clause defines a variable ``f`` representing a Python function. The ``where`` part limits the functions ``f`` to those with more than 7 arguments. Finally, the ``select`` clause lists these functions.
+The ``from`` clause defines a variable ``f`` representing a Python function. The ``where`` part limits the functions ``f`` to those with more than 7 arguments. Finally, the ``select`` clause lists these functions.
 
 .. code-block:: ql
 
@@ -144,7 +136,7 @@ To import the CodeQL library for a specific programming language, type ``import
    where c.getText().regexpMatch("(?si).*\\bTODO\\b.*")
    select c
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2101530483/>`__. The ``from`` clause defines a variable ``c`` representing a JavaScript comment. The ``where`` part limits the comments ``c`` to those containing the word ``"TODO"``. The ``select`` clause lists these comments.
+The ``from`` clause defines a variable ``c`` representing a JavaScript comment. The ``where`` part limits the comments ``c`` to those containing the word ``"TODO"``. The ``select`` clause lists these comments.
 
 .. code-block:: ql
 
@@ -154,9 +146,56 @@ To import the CodeQL library for a specific programming language, type ``import
    where not exists(p.getAnAccess())
    select p
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2098670762/>`__. The ``from`` clause defines a variable ``p`` representing a Java parameter. The ``where`` clause finds unused parameters by limiting the parameters ``p`` to those which are not accessed. Finally, the ``select`` clause lists these parameters.
+The ``from`` clause defines a variable ``p`` representing a Java parameter. The ``where`` clause finds unused parameters by limiting the parameters ``p`` to those which are not accessed. Finally, the ``select`` clause lists these parameters.
 
 Further reading
 ---------------
 
--  For a more technical description of the underlying language, see the ":ref:`QL language reference <ql-language-reference>`."
+-  For a more technical description of the underlying language, see the ":ref:`QL language reference <ql-language-reference>`."
+
+--------------
+
+Answers
+-------
+
+Exercise 1
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   from string s
+   where s = "lgtm"
+   select s.length()
+   
+There is often more than one way to define a query. For example, we can also write the above query in the shorter form:
+
+.. code-block:: ql
+
+   select "lgtm".length()
+
+Exercise 2
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   from float x, float y
+   where x = 3.pow(5) and y = 245.6
+   select x.minimum(y).sin()
+
+Exercise 3
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   from boolean b
+   where b = false
+   select b.booleanNot()
+
+Exercise 4
+~~~~~~~~~~
+
+.. code-block:: ql
+
+   from date start, date end
+   where start = "10/06/2017".toDate() and end = "28/09/2017".toDate()
+   select start.daysTo(end)