Skip to content

Commit 8a65999

Browse files
vchudnov-gvchudnov-g
authored
chore: improve issue templates and directions for filing in correct repo (googleapis#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 googleapis#12651
1 parent 4891320 commit 8a65999

5 files changed

Lines changed: 199 additions & 22 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/bug_report.yaml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: Bug report
2+
description: Create a report to help us improve
3+
labels: ["type: bug","triage me"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
_**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._
9+
- type: checkboxes
10+
attributes:
11+
label: Determine this is the right repository
12+
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.
13+
options:
14+
- label: I determined this is the correct repository in which to report this bug.
15+
required: true
16+
- type: textarea
17+
attributes:
18+
label: Summary of the issue
19+
description: Describe succinctly what you expected to happen, and what actually happened.
20+
placeholder: Describe the issue you encountered
21+
value: |
22+
**Context**
23+
_e.g. I was trying to use the new method Foo_
24+
25+
**Expected Behavior:**
26+
_e.g. I expected method Foo to paginate_
27+
28+
**Actual Behavior:**
29+
_e.g. Method Foo did not paginate_
30+
- type: input
31+
attributes:
32+
label: API client name and version
33+
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).
34+
placeholder: e.g. google-cloud-vision v3.7.2
35+
- type: textarea
36+
attributes:
37+
label: 'Reproduction steps: code'
38+
description: Include a minimal but complete set of Python files that will reproduce the problem.
39+
value: |
40+
file: main.py
41+
```python
42+
def reproduce():
43+
# complete code here
44+
```
45+
46+
<any additional py files>
47+
- type: textarea
48+
attributes:
49+
label: 'Reproduction steps: supporting files'
50+
description: Include any files needed for the code above to work.
51+
value: |
52+
file: mydata.csv
53+
```
54+
alpha,1,3
55+
beta,2,5
56+
```
57+
58+
<any additional supporting files>
59+
- type: textarea
60+
attributes:
61+
label: 'Reproduction steps: actual results'
62+
description: Include the results you got when running your code, such as output files.
63+
value: |
64+
file: output.txtmydata.csv
65+
```
66+
Calculated: foo
67+
```
68+
- type: textarea
69+
attributes:
70+
label: 'Reproduction steps: expected results'
71+
description: Include the results you expected to get when running your code.
72+
value: |
73+
file: output.txtmydata.csv
74+
```
75+
Calculated: bar
76+
```
77+
- type: input
78+
attributes:
79+
label: OS & version + platform
80+
placeholder: e.g. Debian 6.6 on GKE
81+
- type: input
82+
attributes:
83+
label: Python environment
84+
description: Try `python3 --version`.
85+
placeholder: e.g. Python 3.11.8
86+
- type: textarea
87+
attributes:
88+
label: Python dependencies
89+
description: Try `pip list`.
90+
placeholder: |
91+
pip list
92+
Package Version
93+
--------------------------- ------------------------

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/feature_request.yaml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Feature request
2+
description: Request a feature to help us make the libraries more useful
3+
labels: ["type: feature request","triage me"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
_**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._
9+
- type: checkboxes
10+
attributes:
11+
label: Determine this is the right repository
12+
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.
13+
options:
14+
- label: I determined this is the correct repository in which to report this feature request.
15+
required: true
16+
- type: textarea
17+
attributes:
18+
label: Summary of the feature request
19+
description: Describe succinctly what feature you would like the client library to add.
20+
placeholder: Feature request summary
21+
value: |
22+
_e.g. I would like to easily be able to do FOO by simply coding BAR._
23+
- type: textarea
24+
attributes:
25+
label: 'Desired code experience'
26+
description: Include a minimal code snippet of how your requested feature might look in actual code, including how you would use the results.
27+
value: |
28+
file: main.py
29+
```python
30+
def my_ideal_code():
31+
...
32+
some_data = my_new_feature()
33+
do_something_with(some_data))
34+
```
35+
36+
<any additional py files>
37+
- type: textarea
38+
attributes:
39+
label: 'Expected results'
40+
description: Describe the results you would expect with the code above.
41+
value: |
42+
_e.g. `my_new_feature()` should return FOO_
43+
- type: input
44+
attributes:
45+
label: API client name and version
46+
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).
47+
placeholder: e.g. google-cloud-vision v3.7.2

‎SUPPORT.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
**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.
2+
3+
To help us resolve your issue as soon as possible, please follow these steps:
4+
5+
6+
<a id="org49b5b6e"></a>
7+
8+
# Check for already opened issues:
9+
10+
- In `google-cloud-python`: <https://github.com/googleapis/google-cloud-python/issues>
11+
12+
13+
<a id="orge74b7aa"></a>
14+
15+
# *BEFORE* reporting an issue here
16+
17+
- Please determine whether it's a client library issue or an underlying API service issue.
18+
- **Bugs**: Try reproducing the issue without the client library; if you can, then it's an API issue.
19+
- **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.
20+
- To make these determinations, visit [Google APIs Explorer](https://developers.google.com/apis-explorer):
21+
1. Find your API on the [APIs Explorer list](https://developers.google.com/apis-explorer), and follow the link.
22+
2. Click on the API method corresponding to your issue.
23+
3. In the page that appears:
24+
- 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.
25+
- 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`.
26+
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.
27+
28+
29+
<a id="orgb8af98c"></a>
30+
31+
# Filing an API service issue
32+
33+
*(if the issue DID re-occur [above](#orge74b7aa) without using the client library)*
34+
35+
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.
36+
37+
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.
38+
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).
39+
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.
40+
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!
41+
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.
42+
43+
44+
<a id="orge13c134"></a>
45+
46+
# Filing a client library issue
47+
48+
*(if the issue DID NOT re-occur [above](#orge74b7aa) without using the client library)*
49+
50+
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.
51+
52+
- Determine the right repository in which to file:
53+
- 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`).
54+
- 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.
55+
- 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).
56+
- Go to the correct repository, as identified above
57+
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.
58+
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!
59+

0 commit comments

Comments
 (0)