chore: improve issue templates and directions for filing in correct r…

…epo (#12710)

Configures more informative bug and feature report templates on GitHub, and provides users with information and tools to figure out the right place to file their issues for a more prompt and efficient response.

Fixes #12651

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,93 @@
+name: Bug report
+description: Create a report to help us improve
+labels: ["type: bug","triage me"]
+body:
+- type: markdown
+ attributes:
+ value: |
+ _**PLEASE READ**: If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/) instead of filing on GitHub. This will ensure a timely response._
+- type: checkboxes
+ attributes:
+ label: Determine this is the right repository
+ description: Please follow the steps in [the SUPPORT guide](https://github.com/googleapis/google-cloud-python/blob/issue-templates/SUPPORT.md) and determine that this is likely a client library issue and this is the correct repository in which to report it.
+ options:
+ - label: I determined this is the correct repository in which to report this bug.
+ required: true
+- type: textarea
+ attributes:
+ label: Summary of the issue
+ description: Describe succinctly what you expected to happen, and what actually happened.
+ placeholder: Describe the issue you encountered
+ value: |
+ **Context**
+ _e.g. I was trying to use the new method Foo_
+ 
+ **Expected Behavior:**
+ _e.g. I expected method Foo to paginate_
+
+ **Actual Behavior:**
+ _e.g. Method Foo did not paginate_ 
+- type: input
+ attributes:
+ label: API client name and version
+ description: Try `pip list | grep google`, which should give you a name corresponding to one of the packages listed [here](https://github.com/googleapis/google-cloud-python/tree/main/packages).
+ placeholder: e.g. google-cloud-vision v3.7.2
+- type: textarea
+ attributes:
+ label: 'Reproduction steps: code'
+ description: Include a minimal but complete set of Python files that will reproduce the problem.
+ value: |
+ file: main.py
+ ```python
+ def reproduce():
+ # complete code here
+ ```
+
+ <any additional py files>
+- type: textarea
+ attributes:
+ label: 'Reproduction steps: supporting files'
+ description: Include any files needed for the code above to work.
+ value: |
+ file: mydata.csv
+ ```
+ alpha,1,3
+ beta,2,5
+ ```
+
+ <any additional supporting files>
+- type: textarea
+ attributes:
+ label: 'Reproduction steps: actual results'
+ description: Include the results you got when running your code, such as output files.
+ value: |
+ file: output.txtmydata.csv
+ ```
+ Calculated: foo
+ ```
+- type: textarea
+ attributes:
+ label: 'Reproduction steps: expected results'
+ description: Include the results you expected to get when running your code.
+ value: |
+ file: output.txtmydata.csv
+ ```
+ Calculated: bar
+ ```
+- type: input
+ attributes:
+ label: OS & version + platform
+ placeholder: e.g. Debian 6.6 on GKE
+- type: input
+ attributes:
+ label: Python environment
+ description: Try `python3 --version`.
+ placeholder: e.g. Python 3.11.8
+- type: textarea
+ attributes:
+ label: Python dependencies
+ description: Try `pip list`.
+ placeholder: |
+ pip list
+ Package Version
+ --------------------------- ------------------------

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,47 @@
+name: Feature request
+description: Request a feature to help us make the libraries more useful
+labels: ["type: feature request","triage me"]
+body:
+- type: markdown
+ attributes:
+ value: |
+ _**PLEASE READ**: If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/) instead of filing on GitHub. This will ensure a timely response._
+- type: checkboxes
+ attributes:
+ label: Determine this is the right repository
+ description: Please follow the steps in [the SUPPORT guide](https://github.com/googleapis/google-cloud-python/blob/issue-templates/SUPPORT.md) and determine that this is likely a client library issue and this is the correct repository in which to report it.
+ options:
+ - label: I determined this is the correct repository in which to report this feature request.
+ required: true
+- type: textarea
+ attributes:
+ label: Summary of the feature request
+ description: Describe succinctly what feature you would like the client library to add.
+ placeholder: Feature request summary
+ value: |
+ _e.g. I would like to easily be able to do FOO by simply coding BAR._ 
+- type: textarea
+ attributes:
+ label: 'Desired code experience'
+ description: Include a minimal code snippet of how your requested feature might look in actual code, including how you would use the results.
+ value: |
+ file: main.py
+ ```python
+ def my_ideal_code():
+ ...
+ some_data = my_new_feature()
+ do_something_with(some_data))
+ ```
+
+ <any additional py files>
+- type: textarea
+ attributes:
+ label: 'Expected results'
+ description: Describe the results you would expect with the code above.
+ value: |
+ _e.g. `my_new_feature()` should return FOO_
+- type: input
+ attributes:
+ label: API client name and version
+ description: If there's a particular API client for which this feature would be helpful, enter it here. Try `pip list | grep google`, which should give you a name corresponding to one of the packages listed [here](https://github.com/googleapis/google-cloud-python/tree/main/packages).
+ placeholder: e.g. google-cloud-vision v3.7.2

SUPPORT.md

@@ -0,0 +1,59 @@
+**PLEASE READ**: If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/) instead of filing it on GitHub. This will ensure a timely response.
+
+To help us resolve your issue as soon as possible, please follow these steps:
+
+
+<a id="org49b5b6e"></a>
+
+# Check for already opened issues:
+
+- In `google-cloud-python`: <https://github.com/googleapis/google-cloud-python/issues>
+
+
+<a id="orge74b7aa"></a>
+
+# *BEFORE* reporting an issue here
+
+- Please determine whether it's a client library issue or an underlying API service issue.
+ - **Bugs**: Try reproducing the issue without the client library; if you can, then it's an API issue.
+ - **Features**: Determine whether you want something different about the data or how it's changed in Google services (rather than how you access or manipulate it locally); if so, it's an API issue.
+- To make these determinations, visit [Google APIs Explorer](https://developers.google.com/apis-explorer):
+ 1. Find your API on the [APIs Explorer list](https://developers.google.com/apis-explorer), and follow the link.
+ 2. Click on the API method corresponding to your issue.
+ 3. In the page that appears:
+ - You can use the APIs Explorer sidebar (“Try this Method”), fill in your request parameters, and see whether your request succeeds or causes the same error you were getting initially.
+ - Alternatively, you can use the `HTTP Request` listed on that page and any information on the `Request body` to construct a request you can send from the command line using a tool like `curl`.
+ 4. If your request in step 3 above succeeds and is as you expect, then it's likely the resolution centers on the client library; [file a client library issue](#orge13c134) as detailed below. If your request failed or returned unexpected results, then it's likely the resolution centers on the API service; [file an API service issue](#orgb8af98c) instead, as detailed below.
+
+
+<a id="orgb8af98c"></a>
+
+# Filing an API service issue
+
+*(if the issue DID re-occur [above](#orge74b7aa) without using the client library)*
+
+Use the appropriate API service issue tracker. The maintainers of this repo are not experts or contributors on individual API services; we work on generating usable and idiomatic client libraries for many APIs.
+
+1. Consider using [Google Cloud Customer Care](https://cloud.google.com/support/?hl=en) (paid) to get more dedicated support for your issue. Otherwise, continue with the steps below.
+2. Find your API in [the client list at the top of this repository](https://github.com/googleapis/google-cloud-python/tree/main?tab=readme-ov-file#libraries).
+3. Check the “API Issues” column to see whether someone else has reported the same issue. If they have, the filed issue may have some useful information; feel free to add more details or context of your own.
+4. If your issue has not been filed, you can click on “File an API Issue” from the same [client list](https://github.com/googleapis/google-cloud-python/tree/main?tab=readme-ov-file#libraries) to notify the API service team. Be as complete yet succinct as you can!
+5. If you don't see the "API Issues" column for this API (we're in the process of filling out the table), go ahead and file an issue in this repository and make a note that it's likely a service-side issue. We will route it to the right service team.
+
+
+<a id="orge13c134"></a>
+
+# Filing a client library issue
+
+*(if the issue DID NOT re-occur [above](#orge74b7aa) without using the client library)*
+
+Consider using [Google Cloud Customer Care](https://cloud.google.com/support/?hl=en) (paid) to get more dedicated support for your issue. Otherwise, continue with the steps below.
+
+- Determine the right repository in which to file:
+ - If you fetched the API-specific PyPI package, you are probably using one of the modern Python [Cloud Client Libraries](https://cloud.google.com/apis/docs/cloud-client-libraries). Go to [the client list at the top of this repository](https://github.com/googleapis/google-cloud-python/tree/main?tab=readme-ov-file#libraries), which lists them all, and click on the name of your client. That will take you to the correct repository in which to file an issue (for the many APIs listed under [`packages/`](https://github.com/googleapis/google-cloud-python/tree/main/packages), it's this repo, `google-cloud-python`).
+ - If you're using the package `googleapiclient` in your code, you are using the older Python [Google API Client Libraries](https://developers.google.com/api-client-library/), whose source code is hosted in the repository [google-api-python-client](https://github.com/googleapis/google-api-python-client); please file an issue there for those.
+ - For more information on the difference between Cloud Client Libraries and Google API Client Libraries, see [Client Libraries Explained](https://cloud.google.com/apis/docs/client-libraries-explained).
+- Go to the correct repository, as identified above
+ 1. Search for issues already opened (in this repository, those would be in <https://github.com/googleapis/google-cloud-python/issues>). If you find your problem already filed, just add any more context or details that seem appropriate.
+ 2. If your problem has not been previously filed, file an issue. If you're filing in this repository, choose either the [bug report](https://github.com/googleapis/google-cloud-python/issues/new?template=bug_report.yaml) or [feature request](https://github.com/googleapis/google-cloud-python/issues/new?template=feature_request.yaml) template, fill in the details, and submit the issue with an informative title!
+