repo sync

content/repositories/working-with-files/using-files/navigating-code-on-github.md

@@ -15,16 +15,34 @@ topics:
 
 ## About navigating code on {% data variables.product.prodname_dotcom %}
 
-Code navigation uses the open source library [`tree-sitter`](https://github.com/tree-sitter/tree-sitter). The following languages are supported:
-- C#
-- CodeQL
-- Go
-- Java
-- JavaScript
-- PHP
-- Python
-- Ruby
-- TypeScript
+Code navigation helps you to read, navigate, and understand code by showing and linking definitions of a named entity corresponding to a reference to that entity, as well as references corresponding to an entity's definition.
+
+![Code navigation display](/assets/images/help/repository/code-navigation-popover.png)
+
+Code navigation uses the open source [`tree-sitter`](https://github.com/tree-sitter/tree-sitter) library. The following languages and navigation strategies are supported:
+
+| Language   | search-based code navigation | precise code navigation |
+|:----------:|:----------------------------:|:-----------------------:|
+| C#         | ✅                           |                         |
+| CodeQL     | ✅                           |                         |
+| Go         | ✅                           |                         |
+| Java       | ✅                           |                         |
+| JavaScript | ✅                           |                         |
+| PHP        | ✅                           |                         |
+| Python     | ✅                           | ✅                      |
+| Ruby       | ✅                           |                         |
+| TypeScript | ✅                           |                         |
+
+
+You do not need to configure anything in your repository to enable code navigation. We will automatically extract search-based and precise code navigation information for these supported languages in all repositories and you can switch between the two supported code navigation approaches if your programming language is supported by both.
+
+{% data variables.product.prodname_dotcom %} has developed two code navigation approaches based on the open source [`tree-sitter`](https://github.com/tree-sitter/tree-sitter) and [`stack-graphs`](https://github.com/github/stack-graphs) library:
+ - search-based - searches all definitions and references across a repository to find entities with a given name
+ - precise - resolves definitions and references based on the set of classes, functions, and imported definitions at a given point in your code
+
+To learn more about these approaches, see "[Precise and search-based navigation](#precise-and-search-based-navigation)."
+
+Future releases will add *precise code navigation* for more languages, which is a code navigation approach that can give more accurate results.
 
 ## Jumping to the definition of a function or method
 
@@ -38,11 +56,21 @@ You can find all references for a function or method within the same repository
 
 ![Find all references tab](/assets/images/help/repository/find-all-references-tab.png)
 
+## Precise and search-based navigation
+
+Certain languages supported by {% data variables.product.prodname_dotcom %} have access to *precise code navigation*, which uses an algorithm (based on the open source [`stack-graphs`](https://github.com/github/stack-graphs) library) that resolves definitions and references based on the set of classes, functions, and imported definitions that are visible at any given point in your code. Other languages use *search-based code navigation*, which searches all definitions and references across a repository to find entities with a given name. Both strategies are effective at finding results and both make sure to avoid inappropriate results such as comments, but precise code navigation can give more accurate results, especially when a repository contains multiple methods or functions with the same name.
+
+If you don't see the results you expect from a precise code navigation query, you can click on the "search-based" link in the displayed popover to perform search-based navigation.
+
+![Search-based code navigation link](/assets/images/help/repository/search-based-code-navigation-link.png)
+
+If your precise results appear inaccurate, you can file a support request.
+
 ## Troubleshooting code navigation
 
 If code navigation is enabled for you but you don't see links to the definitions of functions and methods:
 - Code navigation only works for active branches. Push to the branch and try again.
-- Code navigation only works for repositories with less than 100,000 files.
+- Code navigation only works for repositories with fewer than 100,000 files.
 
 ## Further reading
 - "[Searching code](/github/searching-for-information-on-github/searching-code)"

data/graphql/ghae/schema.docs-ghae.graphql

@@ -31053,6 +31053,11 @@ type Repository implements Node & ProjectOwner & RepositoryInfo & Starrable & Su
     """
     before: String
 
+    """
+    Filter by categories that are assignable by the viewer.
+    """
+    filterByAssignable: Boolean = false
+
     """
     Returns the first _n_ elements from the list.
     """
@@ -33406,6 +33411,8 @@ Specifies the attributes for a new or updated required status check.
 input RequiredStatusCheckInput {
   """
   The ID of the App that must set the status in order for it to be accepted.
+  Omit this value to use whichever app has recently been setting this status, or
+  use "any" to allow any app to set the status.
   """
   appId: ID
 

data/graphql/ghec/schema.docs.graphql

@@ -34499,6 +34499,11 @@ type Repository implements Node & PackageOwner & ProjectOwner & RepositoryInfo &
     """
     before: String
 
+    """
+    Filter by categories that are assignable by the viewer.
+    """
+    filterByAssignable: Boolean = false
+
     """
     Returns the first _n_ elements from the list.
     """
@@ -36992,6 +36997,8 @@ Specifies the attributes for a new or updated required status check.
 input RequiredStatusCheckInput {
   """
   The ID of the App that must set the status in order for it to be accepted.
+  Omit this value to use whichever app has recently been setting this status, or
+  use "any" to allow any app to set the status.
   """
   appId: ID
 

data/graphql/schema.docs.graphql

@@ -34499,6 +34499,11 @@ type Repository implements Node & PackageOwner & ProjectOwner & RepositoryInfo &
     """
     before: String
 
+    """
+    Filter by categories that are assignable by the viewer.
+    """
+    filterByAssignable: Boolean = false
+
     """
     Returns the first _n_ elements from the list.
     """
@@ -36992,6 +36997,8 @@ Specifies the attributes for a new or updated required status check.
 input RequiredStatusCheckInput {
   """
   The ID of the App that must set the status in order for it to be accepted.
+  Omit this value to use whichever app has recently been setting this status, or
+  use "any" to allow any app to set the status.
   """
   appId: ID
 

data/reusables/supported-languages/python.md

@@ -1 +1 @@
-| Python {% ifversion fpt or ghec %}| {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %}<br>pip | {% octicon "check" aria-label="The check icon" %}<br>pip | {% octicon "check" aria-label="The check icon" %} | {% octicon "x" aria-label="The X icon" %} |{% elsif ghes %}| {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %}<br>pip {% ifversion ghes > 3.2 %}| {% octicon "check" aria-label="The check icon" %}<br>pip{% endif %} | {% octicon "check" aria-label="The check icon" %} | {% octicon "x" aria-label="The X icon" %} |{% elsif ghae %}| {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %} | {% octicon "x" aria-label="The X icon" %} |{% endif %}
+| Python {% ifversion fpt or ghec %}| {% octicon "check" aria-label="The check icon" %} <br>precise| {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %}<br>pip | {% octicon "check" aria-label="The check icon" %}<br>pip | {% octicon "check" aria-label="The check icon" %} | {% octicon "x" aria-label="The X icon" %} |{% elsif ghes %}| {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %}<br>pip {% ifversion ghes > 3.2 %}| {% octicon "check" aria-label="The check icon" %}<br>pip{% endif %} | {% octicon "check" aria-label="The check icon" %} | {% octicon "x" aria-label="The X icon" %} |{% elsif ghae %}| {% octicon "check" aria-label="The check icon" %} | {% octicon "check" aria-label="The check icon" %} | {% octicon "x" aria-label="The X icon" %} |{% endif %}

lib/graphql/static/changelog.json

@@ -1,4 +1,17 @@
 [
+  {
+    "schemaChanges": [
+      {
+        "title": "The GraphQL schema includes these changes:",
+        "changes": [
+          "Argument `filterByAssignable: Boolean` added to field `Repository.discussionCategories`"
+        ]
+      }
+    ],
+    "previewChanges": [],
+    "upcomingChanges": [],
+    "date": "2021-12-09"
+  },
   {
     "schemaChanges": [
       {

lib/graphql/static/schema-dotcom.json

@@ -49044,6 +49044,17 @@
                 "href": "/graphql/reference/scalars#string"
               }
             },
+            {
+              "name": "filterByAssignable",
+              "defaultValue": false,
+              "description": "<p>Filter by categories that are assignable by the viewer.</p>",
+              "type": {
+                "name": "Boolean",
+                "id": "boolean",
+                "kind": "scalars",
+                "href": "/graphql/reference/scalars#boolean"
+              }
+            },
             {
               "name": "first",
               "description": "<p>Returns the first <em>n</em> elements from the list.</p>",
@@ -77385,7 +77396,7 @@
       "inputFields": [
         {
           "name": "appId",
-          "description": "<p>The ID of the App that must set the status in order for it to be accepted.</p>",
+          "description": "<p>The ID of the App that must set the status in order for it to be accepted.\nOmit this value to use whichever app has recently been setting this status, or\nuse \"any\" to allow any app to set the status.</p>",
           "type": "ID",
           "id": "id",
           "kind": "scalars",

lib/graphql/static/schema-ghae.json

@@ -44115,6 +44115,17 @@
                 "href": "/graphql/reference/scalars#string"
               }
             },
+            {
+              "name": "filterByAssignable",
+              "defaultValue": false,
+              "description": "<p>Filter by categories that are assignable by the viewer.</p>",
+              "type": {
+                "name": "Boolean",
+                "id": "boolean",
+                "kind": "scalars",
+                "href": "/graphql/reference/scalars#boolean"
+              }
+            },
             {
               "name": "first",
               "description": "<p>Returns the first <em>n</em> elements from the list.</p>",
@@ -68386,7 +68397,7 @@
       "inputFields": [
         {
           "name": "appId",
-          "description": "<p>The ID of the App that must set the status in order for it to be accepted.</p>",
+          "description": "<p>The ID of the App that must set the status in order for it to be accepted.\nOmit this value to use whichever app has recently been setting this status, or\nuse \"any\" to allow any app to set the status.</p>",
           "type": "ID",
           "id": "id",
           "kind": "scalars",

lib/graphql/static/schema-ghec.json

@@ -49044,6 +49044,17 @@
                 "href": "/graphql/reference/scalars#string"
               }
             },
+            {
+              "name": "filterByAssignable",
+              "defaultValue": false,
+              "description": "<p>Filter by categories that are assignable by the viewer.</p>",
+              "type": {
+                "name": "Boolean",
+                "id": "boolean",
+                "kind": "scalars",
+                "href": "/graphql/reference/scalars#boolean"
+              }
+            },
             {
               "name": "first",
               "description": "<p>Returns the first <em>n</em> elements from the list.</p>",
@@ -77385,7 +77396,7 @@
       "inputFields": [
         {
           "name": "appId",
-          "description": "<p>The ID of the App that must set the status in order for it to be accepted.</p>",
+          "description": "<p>The ID of the App that must set the status in order for it to be accepted.\nOmit this value to use whichever app has recently been setting this status, or\nuse \"any\" to allow any app to set the status.</p>",
           "type": "ID",
           "id": "id",
           "kind": "scalars",