Skip to content

Commit 694c620

Browse files
author
github-actions
committed
docs: Add AI agent issue reporting guidelines and GitHub issue templates
- Add "Reporting Issues to This Package" section to AGENTS.md with MCP GitHub integration instructions and issue body templates - Add "Contributing Pull Requests" section with pre-submission checklist - Create .github/ISSUE_TEMPLATE/ with bug_report.yml, feature_request.yml, documentation.yml, and config.yml
1 parent 8cc7534 commit 694c620

File tree

5 files changed

+540
-0
lines changed

5 files changed

+540
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
name: Bug Report
2+
description: Report a bug or unexpected behavior in ryandata-address-utils
3+
title: "[Bug]: "
4+
labels: ["bug", "needs-triage"]
5+
assignees: []
6+
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for taking the time to report a bug! Please fill out the sections below to help us understand and reproduce the issue.
12+
13+
- type: checkboxes
14+
id: prerequisites
15+
attributes:
16+
label: Prerequisites
17+
description: Please confirm the following before submitting
18+
options:
19+
- label: I have searched existing issues to ensure this bug hasn't already been reported
20+
required: true
21+
- label: I am using the latest version of ryandata-address-utils
22+
required: true
23+
- label: I have read the [documentation](https://github.com/Abstract-Data/RyanData-Address-Utils#readme)
24+
required: false
25+
26+
- type: textarea
27+
id: description
28+
attributes:
29+
label: Bug Description
30+
description: A clear and concise description of what the bug is
31+
placeholder: Describe the bug...
32+
validations:
33+
required: true
34+
35+
- type: textarea
36+
id: reproduction
37+
attributes:
38+
label: Steps to Reproduce
39+
description: Minimal code example that reproduces the issue
40+
placeholder: |
41+
```python
42+
from ryandata_address_utils import AddressService, parse
43+
44+
# Code that triggers the bug...
45+
result = parse("123 Main St, Austin TX 78749")
46+
```
47+
render: python
48+
validations:
49+
required: true
50+
51+
- type: textarea
52+
id: expected
53+
attributes:
54+
label: Expected Behavior
55+
description: What did you expect to happen?
56+
placeholder: I expected...
57+
validations:
58+
required: true
59+
60+
- type: textarea
61+
id: actual
62+
attributes:
63+
label: Actual Behavior
64+
description: What actually happened?
65+
placeholder: Instead, what happened was...
66+
validations:
67+
required: true
68+
69+
- type: dropdown
70+
id: component
71+
attributes:
72+
label: Affected Component
73+
description: Which part of the library is affected?
74+
multiple: true
75+
options:
76+
- AddressService (main facade)
77+
- Address Model / Pydantic
78+
- Parsers (usaddress / libpostal)
79+
- Validators (ZIP / State)
80+
- Data Sources (ZIP lookup)
81+
- Pandas Integration
82+
- CLI (setup / TUI)
83+
- ProcessLog / Cleaning Tracking
84+
- Other / Unknown
85+
validations:
86+
required: true
87+
88+
- type: textarea
89+
id: error-output
90+
attributes:
91+
label: Error Output / Stack Trace
92+
description: If applicable, paste the full error message or stack trace
93+
placeholder: |
94+
Traceback (most recent call last):
95+
File "...", line X, in <module>
96+
...
97+
Error: ...
98+
render: shell
99+
100+
- type: dropdown
101+
id: python-version
102+
attributes:
103+
label: Python Version
104+
description: Which Python version are you using?
105+
options:
106+
- "3.13"
107+
- "3.12"
108+
validations:
109+
required: true
110+
111+
- type: input
112+
id: package-version
113+
attributes:
114+
label: Package Version
115+
description: "Run: python -c \"import ryandata_address_utils; print(ryandata_address_utils.__version__)\""
116+
placeholder: "e.g., 0.7.1"
117+
validations:
118+
required: true
119+
120+
- type: dropdown
121+
id: os
122+
attributes:
123+
label: Operating System
124+
options:
125+
- macOS
126+
- Linux
127+
- Windows
128+
- Other
129+
validations:
130+
required: true
131+
132+
- type: textarea
133+
id: additional
134+
attributes:
135+
label: Additional Context
136+
description: Any other context, screenshots, or information that might help
137+
placeholder: Add any other context here...

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Questions & Discussions
4+
url: https://github.com/Abstract-Data/RyanData-Address-Utils/discussions
5+
about: For questions, help, and general discussion - please use GitHub Discussions instead of opening an issue.
6+
- name: Security Vulnerabilities
7+
url: https://github.com/Abstract-Data/RyanData-Address-Utils/security/advisories/new
8+
about: Report security vulnerabilities privately through GitHub Security Advisories.

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: Documentation Issue
2+
description: Report missing, incorrect, or unclear documentation
3+
title: "[Docs]: "
4+
labels: ["documentation"]
5+
assignees: []
6+
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Help us improve the documentation! Please describe what needs to be added, corrected, or clarified.
12+
13+
- type: dropdown
14+
id: issue-type
15+
attributes:
16+
label: Documentation Issue Type
17+
description: What kind of documentation issue is this?
18+
options:
19+
- Missing documentation (feature not documented)
20+
- Incorrect documentation (docs don't match behavior)
21+
- Unclear documentation (hard to understand)
22+
- Needs code example (missing or incomplete examples)
23+
- Typo or formatting issue
24+
- Outdated documentation (refers to old API/behavior)
25+
validations:
26+
required: true
27+
28+
- type: dropdown
29+
id: location
30+
attributes:
31+
label: Documentation Location
32+
description: Where is the documentation issue located?
33+
multiple: true
34+
options:
35+
- README.md
36+
- AGENTS.md (AI guidelines)
37+
- docs/ARCHITECTURE.md
38+
- Module docstrings
39+
- API reference / type hints
40+
- Code comments
41+
- Other / New documentation needed
42+
validations:
43+
required: true
44+
45+
- type: input
46+
id: section
47+
attributes:
48+
label: Specific Section
49+
description: If applicable, which section or heading?
50+
placeholder: "e.g., 'Working with Pandas' or 'AddressService.parse()'"
51+
52+
- type: textarea
53+
id: current
54+
attributes:
55+
label: Current Documentation
56+
description: What does the current documentation say (if applicable)?
57+
placeholder: |
58+
The current docs state:
59+
> "..."
60+
61+
Or link to the section: https://github.com/...#section
62+
63+
- type: textarea
64+
id: problem
65+
attributes:
66+
label: Problem Description
67+
description: What's wrong or missing?
68+
placeholder: |
69+
The documentation doesn't explain how to...
70+
71+
The example is confusing because...
72+
73+
This section is incorrect - the actual behavior is...
74+
validations:
75+
required: true
76+
77+
- type: textarea
78+
id: suggestion
79+
attributes:
80+
label: Suggested Improvement
81+
description: How should the documentation be improved?
82+
placeholder: |
83+
The documentation should:
84+
- Explain that...
85+
- Include an example showing...
86+
- Clarify that...
87+
validations:
88+
required: true
89+
90+
- type: checkboxes
91+
id: contribution
92+
attributes:
93+
label: Contribution
94+
description: Would you be willing to help improve the documentation?
95+
options:
96+
- label: I would be willing to submit a PR with documentation improvements
97+
required: false
98+
99+
- type: textarea
100+
id: additional
101+
attributes:
102+
label: Additional Context
103+
description: Any other context or references
104+
placeholder: |
105+
Related to: #...
106+
See also: ...

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
name: Feature Request
2+
description: Suggest a new feature or enhancement for ryandata-address-utils
3+
title: "[Feature]: "
4+
labels: ["enhancement", "needs-triage"]
5+
assignees: []
6+
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for suggesting a feature! Please describe your idea clearly so we can understand and evaluate it.
12+
13+
- type: checkboxes
14+
id: prerequisites
15+
attributes:
16+
label: Prerequisites
17+
description: Please confirm the following before submitting
18+
options:
19+
- label: I have searched existing issues to ensure this feature hasn't already been requested
20+
required: true
21+
- label: I have read the [documentation](https://github.com/Abstract-Data/RyanData-Address-Utils#readme) to confirm this feature doesn't already exist
22+
required: true
23+
24+
- type: textarea
25+
id: problem
26+
attributes:
27+
label: Problem Statement
28+
description: What problem does this feature solve? What limitation or pain point does it address?
29+
placeholder: |
30+
I'm trying to accomplish X, but currently I have to...
31+
32+
This is frustrating because...
33+
validations:
34+
required: true
35+
36+
- type: textarea
37+
id: solution
38+
attributes:
39+
label: Proposed Solution
40+
description: Describe what you'd like to see implemented
41+
placeholder: |
42+
I would like a way to...
43+
44+
The API could look something like:
45+
```python
46+
# Example usage
47+
```
48+
validations:
49+
required: true
50+
51+
- type: textarea
52+
id: alternatives
53+
attributes:
54+
label: Alternatives Considered
55+
description: What other approaches have you considered or tried?
56+
placeholder: |
57+
I've tried working around this by...
58+
59+
Another approach could be...
60+
61+
- type: dropdown
62+
id: component
63+
attributes:
64+
label: Affected Component
65+
description: Which part of the library would this feature affect?
66+
multiple: true
67+
options:
68+
- AddressService (main facade)
69+
- Address Model / Pydantic
70+
- Parsers (usaddress / libpostal)
71+
- Validators (ZIP / State)
72+
- Data Sources (ZIP lookup)
73+
- Pandas Integration
74+
- CLI (setup / TUI)
75+
- ProcessLog / Cleaning Tracking
76+
- New Component
77+
- Other
78+
validations:
79+
required: true
80+
81+
- type: textarea
82+
id: use-case
83+
attributes:
84+
label: Use Case Example
85+
description: Provide a concrete example showing how this feature would be used
86+
placeholder: |
87+
```python
88+
from ryandata_address_utils import AddressService
89+
90+
# Example showing the feature in action
91+
service = AddressService()
92+
93+
# This new feature would allow me to:
94+
result = service.new_feature(...)
95+
```
96+
render: python
97+
validations:
98+
required: true
99+
100+
- type: dropdown
101+
id: priority
102+
attributes:
103+
label: How important is this feature to you?
104+
options:
105+
- Nice to have
106+
- Would significantly improve my workflow
107+
- Blocking my use case
108+
validations:
109+
required: true
110+
111+
- type: checkboxes
112+
id: contribution
113+
attributes:
114+
label: Contribution
115+
description: Would you be willing to help implement this feature?
116+
options:
117+
- label: I would be willing to submit a PR for this feature
118+
required: false
119+
120+
- type: textarea
121+
id: additional
122+
attributes:
123+
label: Additional Context
124+
description: Any other context, mockups, or references that might help
125+
placeholder: |
126+
Related issues: #...
127+
Similar features in other libraries: ...
128+
Additional notes: ...

0 commit comments

Comments
 (0)