Merge branch 'trunk' into eugene/fetch-ref-handle-ReleaseNotFound

docs/triage.md

@@ -6,10 +6,12 @@ As we get more issues and pull requests opened on the GitHub CLI, we've decided
 
 Review and label [open issues missing either the `enhancement`, `bug`, or `docs` label](https://github.com/cli/cli/issues?q=is%3Aopen+is%3Aissue+-label%3Abug%2Cenhancement%2Cdocs+) and the label(s) corresponding to the command space prefixed with `gh-`, such as `gh-pr` for the `gh pr` command set, or `gh-extension` for the `gh extension` command set. 
 
-Then, engage with the issue and community with the goal to remove the `needs-triage` label from the issue. The heuristics for triaging the different issue types are as follow:
+The heuristics for triaging the different issue types are as follows:
 
 ### Bugs
 
+For bugs, the FR should engage with the issue and community with the goal to remove the `needs-triage` label from the issue.
+
 To be considered triaged, `bug` issues require the following:
 
 - A severity label `p1`, `p2`, and `p3`
@@ -23,33 +25,55 @@ To be considered triaged, `bug` issues require the following:
 | `p2` | Affects more than a few users but doesn't prevent core functions |
 | `p3` | Affects a small number of users or is largely cosmetic |
 
-### Enhancements
+### Enhancements and Docs
 
-To be considered triaged, `enhancement` issues require either
+For `enhancement` issues, the FR's role is to prepare the issue for team review and triage.
 
-- Clearly defined Acceptance Criteria as above 
-- The `needs-investigation` or `needs-design` label with a clearly defined set of open questions to be investigated.
+When a new issue is opened, the FR **should**:
 
-### Docs
+- Acknowledge the issue
+- Assign themselves to the issue
+- Ensure there is enough information to understand the enhancement's scope and value
+- Ask the user for more information about value and use-case, if necessary
+- Leave the `needs-triage` label on the issue
+- Add the `needs-user-input` and `needs-investigation` labels as needed
 
-To be considered triaged, `docs` issues require clearly defined Acceptance Criteria, as defined above 
+When the FR has enough information to be triaged, they should:
+- Remove the `needs-user-input` and `needs-investigation` labels
+- Remove their assignment from the issue
 
-## Additional triaging processes and labels
+The FR should **avoid**:
 
-Before removing the `needs-triage` label, consider adding any of the following labels below.
+- Thoroughly investigating the enhancement's technical feasibility
+- Prematurely accepting the enhancement request
+- Removing the `needs-triage` label
+- Labeling issues as `help wanted`
+
+## Additional triaging labels
+
+The FR can consider adding any of the following labels below.
 
 | Label | Description |
 | - | - |
 | `discuss` | Some issues require discussion with the internal team. Adding this label will automatically open up an internal discussion with the team to facilitate this discussion. |
 | `core` |  Defines what we would like to do internally. We tend to lean towards `help wanted` by default, and adding `core` should be reserved for trickier issues or implementations we have strong opinions/preferences about. |
-| `good first issue` | Used to denote when an issue may be a good candidate for a first-time contributor to the CLI. These are usually small and well defined issues. |
-| `help wanted` |  Defines what we feel the community could solve should they care to contribute, respectively. We tend to lean towards `help wanted` by default, and adding `core` should be reserved for trickier issues or implementations we have strong opinions/preferences about. |
-| `invalid` | Added to spam and abusive issues. |
 | `needs-user-input` | After asking any contributors for more information, add this label so it is clear that the issue has been responded to and we are waiting on the user. |
+| `needs-investigation` | Used when the issue requires further investigation before it can be reviewed and triaged. This is often used for issues that are not clearly bugs or enhancements, or when the FR needs to gather more information before proceeding. |
+| `invalid` | Added to spam and abusive issues. |
+
+### Labels for team enhancement triaging
+
+The FR should **avoid** adding these labels outside of team enhancement triage.
+
+| Label | Description |
+| - | - |
+| `good first issue` | Used to denote when an issue may be a good candidate for a first-time contributor to the CLI. These are usually small and well defined issues. |
+| `help wanted` | These issues are ready for community contribution. |
+| `help wanted candidate` | Used to denote when an issue may be a good candidate for community contribution. Issues labelled this way are discussed internally and may be promoted to `help wanted`. |
 
 ## Expectations for community pull requests
 
-All incoming pull requests are assigned to one of the engineers for review on a round-robin basis.
+All incoming pull requests are assigned to one of the engineers for review on a load-balanced basis.
 The person in a triage role for a week could take a glance at these pull requests, mostly to see whether
 the changeset is feasible and to allow the associated CI run for new contributors.
 

go.mod

@@ -2,7 +2,7 @@ module github.com/cli/cli/v2
 
 go 1.24.0
 
-toolchain go1.24.5
+toolchain go1.24.6
 
 require (
 	github.com/AlecAivazis/survey/v2 v2.3.7
@@ -47,7 +47,7 @@ require (
 	github.com/sigstore/protobuf-specs v0.5.0
 	github.com/sigstore/sigstore-go v1.1.0
 	github.com/spf13/cobra v1.9.1
-	github.com/spf13/pflag v1.0.6
+	github.com/spf13/pflag v1.0.7
 	github.com/stretchr/testify v1.10.0
 	github.com/theupdateframework/go-tuf/v2 v2.1.1
 	github.com/yuin/goldmark v1.7.12

go.sum

@@ -1363,8 +1363,9 @@ github.com/spf13/cast v1.9.2 h1:SsGfm7M8QOFtEzumm7UZrZdLLquNdzFYfIbEXntcFbE=
 github.com/spf13/cast v1.9.2/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
 github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
 github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
-github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
 github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.7 h1:vN6T9TfwStFPFM5XzjsvmzZkLuaLX+HS+0SeFLRgU6M=
+github.com/spf13/pflag v1.0.7/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.20.1 h1:ZMi+z/lvLyPSCoNtFCpqjy0S4kPbirhpTMwl8BkW9X4=
 github.com/spf13/viper v1.20.1/go.mod h1:P9Mdzt1zoHIG8m2eZQinpiBjo6kCmZSKBClNNqjJvu4=
 github.com/spiffe/go-spiffe/v2 v2.5.0 h1:N2I01KCUkv1FAjZXJMwh95KK1ZIQLYbPfhaxw8WS0hE=

pkg/cmd/search/code/code.go

@@ -46,6 +46,8 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman
 			Note that these search results are powered by what is now a legacy GitHub code search engine.
 			The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search
 			are not yet available via the GitHub API.
+
+			For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s.
 		`, "`"),
 		Example: heredoc.Doc(`
 			# Search code matching "react" and "lifecycle"

pkg/cmd/search/commits/commits.go

@@ -37,7 +37,7 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra.
 	cmd := &cobra.Command{
 		Use:   "commits [<query>]",
 		Short: "Search for commits",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Search for commits on GitHub.
 
 			The command supports constructing queries using the GitHub search syntax,
@@ -45,7 +45,9 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra.
 
 			GitHub search syntax is documented at:
 			<https://docs.github.com/search-github/searching-on-github/searching-commits>
-		`),
+
+			For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Search commits matching set of keywords "readme" and "typo"
 			$ gh search commits readme typo

pkg/cmd/search/issues/issues.go

@@ -26,7 +26,7 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c
 	cmd := &cobra.Command{
 		Use:   "issues [<query>]",
 		Short: "Search for issues",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Search for issues on GitHub.
 
 			The command supports constructing queries using the GitHub search syntax,
@@ -34,7 +34,9 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c
 
 			GitHub search syntax is documented at:
 			<https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests>
-		`),
+
+			For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Search issues matching set of keywords "readme" and "typo"
 			$ gh search issues readme typo

pkg/cmd/search/prs/prs.go

@@ -28,7 +28,7 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr
 	cmd := &cobra.Command{
 		Use:   "prs [<query>]",
 		Short: "Search for pull requests",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Search for pull requests on GitHub.
 
 			The command supports constructing queries using the GitHub search syntax,
@@ -36,7 +36,9 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr
 
 			GitHub search syntax is documented at:
 			<https://docs.github.com/search-github/searching-on-github/searching-issues-and-pull-requests>
-		`),
+
+			For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Search pull requests matching set of keywords "fix" and "bug"
 			$ gh search prs fix bug

pkg/cmd/search/repos/repos.go

@@ -38,7 +38,7 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm
 	cmd := &cobra.Command{
 		Use:   "repos [<query>]",
 		Short: "Search for repositories",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Search for repositories on GitHub.
 
 			The command supports constructing queries using the GitHub search syntax,
@@ -46,7 +46,9 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm
 
 			GitHub search syntax is documented at:
 			<https://docs.github.com/search-github/searching-on-github/searching-for-repositories>
-		`),
+
+			For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Search repositories matching set of keywords "cli" and "shell"
 			$ gh search repos cli shell

pkg/cmd/search/search.go

@@ -1,6 +1,7 @@
 package search
 
 import (
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/pkg/cmdutil"
 	"github.com/spf13/cobra"
 
@@ -15,7 +16,33 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "search <command>",
 		Short: "Search for repositories, issues, and pull requests",
-		Long:  "Search across all of GitHub.",
+		Long: heredoc.Docf(`
+			Search across all of GitHub.
+
+			Excluding search results that match a qualifier
+
+			In a browser, the GitHub search syntax supports excluding results that match a search qualifier
+			by prefixing the qualifier with a hyphen. For example, to search for issues that
+			do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier.
+
+			%[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra
+			command line arguments to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen.
+
+			On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that
+			the arguments that follow are not a flag, but rather a query string. For example:
+
+			$ gh search issues -- "my-search-query -label:bug"
+
+			On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to
+			produce the same effect. For example:
+
+			$ gh --%[2]s search issues -- "my search query -label:bug"
+
+			See the following for more information:
+			- GitHub search syntax: <https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#exclude-results-that-match-a-qualifier>
+			- The PowerShell stop parse flag %[1]s--%[2]s%[1]s: <https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5#the-stop-parsing-token>
+			- The Unix-like %[1]s--%[1]s argument: <https://www.gnu.org/software/bash/manual/bash.html#Shell-Builtin-Commands-1>
+		`, "`", "%"),
 	}
 
 	cmd.AddCommand(searchCodeCmd.NewCmdCode(f, nil))