Skip to content

Commit 2e0aa5f

Browse files
simonjbeaumontsimonjbeaumont
authored
Add Github issue template forms (#477)
### Motivation Github recently added support for Issue forms, which can help guide the creation of issues for adopters and developers to provide the critical information needed to diagnose issues. These have recently been adopted by the Swift project too, from which our templates take much inspiration. When using issue forms (and templates in general) it also provides the filer with a choice of what kind of issue it is, and can automatically add appropriate labels based on kind and apply the `status/triage` label. Finally the page that displays the choice of issue templates can be further extended to provide links to other useful external resources. Note that it is still possible to create an issue from a blank slate if none of the options suit the adopter. Check out the "New issue" page on apple/swift to see all these features combined and in action[^1]. [^1]: https://github.com/apple/swift/issues/new/choose ### Modifications - Add template for reporting a bug: - Disclaimer that this is not for Xcode issues. - Required fields for versions, reproduction steps, expected behavior. - Optional fields for additional information. - Applies labels: `kind/bug`, `status/triage`. - Add template for asking a question: - Disclaimer that this is not for Xcode support. - Links to FAQ. - Applies labels: `kind/support`, `status/triage`. - Add template for requesting a feature: - Explains the proposal process. - Required fields for cut-down proposal input. - Applies labels: `kind/feature`, `status/triage`. - Add template for tracking a task: - Meant for maintainers and for breaking out issues from PRs or quotes from bugs. - Applies labels: `kind/enhancement`, `status/triage`. - Added additional resources to chooser: - Documentation - Examples - FAQ - Supported OpenAPI features - Proposal process - Swift Open Source Slack channel - Feedback Assistant for Xcode and URLSession bugs - Kept the blank issues enabled. ### Result More guided process when filing issues and surfaces other relevant resources. ### Test Plan None.
1 parent 0779747 commit 2e0aa5f

File tree

6 files changed

+275
-0
lines changed

6 files changed

+275
-0
lines changed

Diff for: ‎.github/ISSUE_TEMPLATE/bug-report.yml

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
name: 🐞 Report a bug
2+
description: >
3+
Report a deviation from expected or documented behavior, but not a crash.
4+
labels: [kind/bug, status/triage]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: >
9+
This repository hosts issues for the Swift OpenAPI generator, the Swift
10+
OpenAPI runtime library, the Swift OpenAPI URLSession transport library,
11+
and the AsyncHTTPClient transport library.
12+
It does *not* track feedback on Xcode and other closed source Apple
13+
developer software such as URLSession itself; please direct it to
14+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
15+
16+
___
17+
- type: textarea
18+
attributes:
19+
label: Description
20+
description: >
21+
A concise description of what causes the problem, in human language.
22+
Though not required, it may help us to more accurately triage the issue
23+
as well as understand a non-trivial test case.
24+
validations:
25+
required: false
26+
- type: textarea
27+
attributes:
28+
label: Reproduction
29+
description: >
30+
Please provide inputs to help us reproduce the issue.
31+
32+
If the issue relates to code generation, provide an example OpenAPI
33+
document, a generator configuration file, and extract of the Swift
34+
code you believe to contain the issue. If generation fails, please
35+
provide the generator output.
36+
37+
If the issue is with using the generated code, or the runtime or
38+
transport libraries, provide a test case, provide sample Swift code, and
39+
explain how to build or run it to reproduce the problem.
40+
41+
If the problem is a poor or unexpected error, warning, or output, please
42+
show them.
43+
44+
Consider reducing the test case to the smallest amount of code possible
45+
— a smaller test case is easier to reason about and more appealing to
46+
contributors.
47+
placeholder: |
48+
```yaml
49+
# openapi.yaml
50+
openapi: '3.1.0'
51+
...
52+
```
53+
54+
```yaml
55+
# openapi-generator-config.yaml
56+
mode:
57+
- types
58+
- client
59+
...
60+
```
61+
62+
```swift
63+
let message = try await client.getGreeting()
64+
```
65+
validations:
66+
required: true
67+
- type: textarea
68+
attributes:
69+
label: Package version(s)
70+
description: >
71+
Provide the versions of the relevant Swift OpenAPI packages used when
72+
encountering the issue.
73+
placeholder: |
74+
```console
75+
% swift package show-dependencies
76+
```
77+
validations:
78+
required: true
79+
- type: textarea
80+
attributes:
81+
label: Expected behavior
82+
description: >
83+
Describe the behavior you expected.
84+
validations:
85+
required: true
86+
- type: textarea
87+
attributes:
88+
label: Environment
89+
description: >
90+
Provide the Swift version, tag, or revision. If you suspect that the
91+
problem might be specific to a particular development platform or
92+
deployment target, please specify them as well.
93+
placeholder: |
94+
```console
95+
% swift -version
96+
97+
% sw_vers ||
98+
```
99+
validations:
100+
required: true
101+
- type: textarea
102+
attributes:
103+
label: Additional information
104+
description: >
105+
Any complementary information that could help others to work around
106+
the problem, and us to better understand the problem and its impact.
107+
For example, a link to a discussion or post that motivated this
108+
report.
109+
validations:
110+
required: false

Diff for: ‎.github/ISSUE_TEMPLATE/config.yml

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: 📖 Learn about Swift OpenAPI Generator
4+
url: https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/
5+
about: >
6+
Read the rendered Swift OpenAPI Generator documentation on Swift Package Index.
7+
- name: 🧑‍🏫 Example projects
8+
url: https://github.com/apple/swift-openapi-generator/blob/main/Examples/README.md
9+
about: >
10+
Build, run, and experiment with sample projects that use Swift OpenAPI
11+
Generator and integrate with other packages in the ecosystem.
12+
- name: ✅ Take a look at the FAQ
13+
url: https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/useful-openapi-patterns
14+
about: >
15+
See solutions to commonly-asked questions and common workflows.
16+
- name: 🧩 Check the list of supported OpenAPI features
17+
url: https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/supported-openapi-features
18+
about: >
19+
See which features of the OpenAPI Specification are currently supported by
20+
the Swift OpenAPI Generator.
21+
- name: 📄 Formally propose a change
22+
url: https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/proposals
23+
about: >
24+
Formally propose an addition, removal, or change to the features of the
25+
Swift OpenAPI Generator using the proposal process.
26+
- name: 💬 Join the \#openapi Slack channel
27+
url: https://swift-open-source.slack.com/archives/C05AZ55J75K
28+
about: >
29+
Chat with other adopters and contributors on the Swift Open Source Slack
30+
workspace.
31+
- name: 🪲 Report an issue using Feedback Assistant
32+
url: https://developer.apple.com/bug-reporting
33+
about: >
34+
Report an issue with Xcode or other closed source Apple developer
35+
software such as URLSession.

Diff for: ‎.github/ISSUE_TEMPLATE/feature-request.yml

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: 🌟 Request a change
2+
description: >
3+
Request a feature, improvement, or other change.
4+
labels: [kind/feature, status/triage]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: >
9+
This repository hosts issues for the Swift OpenAPI generator, the Swift
10+
OpenAPI runtime library, the Swift OpenAPI URLSession transport library,
11+
and the AsyncHTTPClient transport library.
12+
It does *not* track feedback on Xcode and other closed source Apple
13+
developer software such as URLSession itself; please direct it to
14+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
15+
16+
___
17+
18+
For non-trivial changes that affect the public API, the Swift OpenAPI
19+
Generator project adopts a ligthweight version of the [Swift
20+
Evolution](https://github.com/apple/swift-evolution/blob/main/process.md)
21+
process.
22+
23+
Writing a proposal first helps discuss multiple possible solutions
24+
early, apply useful feedback from other contributors, and avoid
25+
reimplementing the same feature multiple times.
26+
27+
Use this issue template to start discussion about your feature request.
28+
- type: textarea
29+
attributes:
30+
label: Motivation
31+
description: >
32+
Describe the problems that this proposal aims to address, and what
33+
workarounds adopters have to employ currently, if any.
34+
validations:
35+
required: true
36+
- type: textarea
37+
attributes:
38+
label: Proposed solution
39+
description: >
40+
Describe your solution to the problem. Provide examples and describe how they
41+
work. Show how your solution is better than current workarounds.
42+
validations:
43+
required: true
44+
- type: textarea
45+
attributes:
46+
label: Alternatives considered
47+
description: >
48+
Any alternative approaches that were considered, and why the *proposed
49+
solution* was chosen instead.
50+
validations:
51+
required: false
52+
- type: textarea
53+
attributes:
54+
label: Additional information
55+
description: >
56+
Any complementary information that could be valuable to an author of a
57+
formal proposal, an implementor, or future discussions. For example, a
58+
link to a discussion or post that motivated this request.
59+
validations:
60+
required: false

Diff for: ‎.github/ISSUE_TEMPLATE/support-request.yml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: 🙋 Ask a question
2+
description: >
3+
Ask a question about or get help with Swift OpenAPI Generator. Beginner
4+
questions welcome!
5+
labels: [kind/support, status/triage]
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: >
10+
This repository hosts issues for the Swift OpenAPI generator, the Swift
11+
OpenAPI runtime library, the Swift OpenAPI URLSession transport library,
12+
and the AsyncHTTPClient transport library.
13+
It does *not* track feedback on Xcode and other closed source Apple
14+
developer software such as URLSession itself; please direct it to
15+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
16+
17+
___
18+
19+
Please use this issue template to ask a question.
20+
21+
You may also like to check out our
22+
[FAQ](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/useful-openapi-patterns)
23+
for solutions to frequently asked questions and common workflows.
24+
- type: textarea
25+
attributes:
26+
label: Question
27+
description: >
28+
What are you trying to achieve? What have you tried? What didn't work as expected?
29+
validations:
30+
required: true

Diff for: ‎.github/ISSUE_TEMPLATE/task.yml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: ⚙️ Track a task
2+
description: >
3+
Tasks can be used to track internal work, extract individual subtasks from a
4+
larger issue, and can serve as umbrella issues themselves.
5+
labels: [kind/enhancement, status/triage]
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: >
10+
This repository hosts issues for the Swift OpenAPI generator, the Swift
11+
OpenAPI runtime library, the Swift OpenAPI URLSession transport library,
12+
and the AsyncHTTPClient transport library.
13+
It does *not* track feedback on Xcode and other closed source Apple
14+
developer software such as URLSession itself; please direct it to
15+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
16+
17+
___
18+
- type: textarea
19+
attributes:
20+
label: Description
21+
description: >
22+
A comprehensive description of the task, in human language.
23+
validations:
24+
required: true
25+
- type: textarea
26+
attributes:
27+
label: Additional information
28+
description: >
29+
Any complementary information that could be valuable to an implementor.
30+
validations:
31+
required: false

Diff for: ‎NOTICE.txt

+9
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,15 @@ This product contains derivations of various scripts and templates from SwiftNIO
3535

3636
-------------------------------------------------------------------------------
3737

38+
This product contains derivations of templates and proposal workflows from Swift.
39+
40+
* LICENSE (Apache License 2.0):
41+
* https://swift.org/LICENSE.txt
42+
* HOMEPAGE:
43+
* https://github.com/apple/swift
44+
45+
-------------------------------------------------------------------------------
46+
3847
This product contains derivations of examples from the OpenAPI project.
3948

4049
* LICENSE (Apache License 2.0):

0 commit comments

Comments
 (0)