Skip to content

Commit 47cacd2

Browse files
stmontgomerystmontgomery
authored
Improve the project's GitHub Issue templates (#962)
This includes several improvements to this project's GitHub Issue templates. ### Motivation: Some of these changes are meant to guide users to provide more useful information when filing issues, or point them to other places when appropriate. Other changes are meant to help contributors and maintainers better organize issues in the project. ### Modifications: - Add a `config.yml` to add several related links in the New Issue template chooser to related places like the our Forums category, the bug report links for related tools, and documentation. - Modify the "Bug Report" template: - Rename it to "Report a bug" and clarify its description. - Modify its fields to more clearly explain each question and consolidate some. - Modify the "Feature Request" template: - Rename it to "Request a change" and clarify its description. - Modify fields to be more relevant to a change request. - Add a "Task" template. - Added a (newly created) `triage-needed` label to the "Bug Report" and "Request a Change" templates so we can distinguish those which have not yet been triaged. - Add notes to the top of several templates about how they're not meant for Xcode feedback, and directing major ideas to the Forums instead. - Add copyright header to all template-related files. - Add numbers to the template files to control their display order. - Switch to kebab-case file names for the templates. ### Checklist: - [x] Code and documentation should follow the style of the [Style Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md). - [x] If public symbols are renamed or modified, DocC references should be updated.
1 parent 243bba9 commit 47cacd2

File tree

6 files changed

+221
-78
lines changed

6 files changed

+221
-78
lines changed

‎.github/ISSUE_TEMPLATE/01-bug-report.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2025 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
name: 🪲 Report a bug
10+
description: >
11+
Report a deviation from expected or documented behavior.
12+
labels: [bug, triage-needed]
13+
body:
14+
- type: markdown
15+
attributes:
16+
value: >
17+
This repository hosts the Swift Testing library and its documentation.
18+
It does _not_ track feedback for Xcode and other closed source Apple
19+
developer software such as XCTest; please direct that to
20+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
21+
- type: textarea
22+
attributes:
23+
label: Description
24+
description: >
25+
A concise description of what causes the problem, in human language.
26+
Though not required, it may help us to more accurately triage the issue
27+
as well as understand a non-trivial test case.
28+
validations:
29+
required: false
30+
- type: textarea
31+
attributes:
32+
label: Reproduction
33+
description: >
34+
Provide an example, preferably in a Markdown code block, and explain how
35+
to build or run it to reproduce the problem. If the problem is a poor or
36+
unexpected diagnostic, fix-it, or other output, please show this output
37+
as is. For example, paste it from the terminal. Consider reducing the
38+
example to the smallest amount of code possible — a smaller example is
39+
easier to reason about and more appealing to contributors.
40+
value: |
41+
```swift
42+
43+
```
44+
validations:
45+
required: true
46+
- type: textarea
47+
attributes:
48+
label: Expected behavior
49+
description: Describe the behavior you expected.
50+
validations:
51+
required: true
52+
- type: textarea
53+
attributes:
54+
label: Environment
55+
description: >
56+
Provide details about the environment in which this problem occurs.
57+
Include the versions of Swift Testing and the Swift toolchain. If you
58+
suspect the problem might be specific to a particular platform, please
59+
specify the platform and OS version as well.
60+
placeholder: |
61+
Swift Testing version: (shown in `swift test` output)
62+
$ swift --version
63+
$ uname -a
64+
validations:
65+
required: true
66+
- type: textarea
67+
attributes:
68+
label: Additional information
69+
description: >
70+
Any complementary information that could help others to work around the
71+
problem, and us to better understand the problem and its impact. For
72+
example, a link to a discussion or post that motivated this report.
73+
validations:
74+
required: false

‎.github/ISSUE_TEMPLATE/02-change-request.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2025 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
name: 🌟 Request a change
10+
description: >
11+
Request a feature, API, improvement, or other change.
12+
labels: [enhancement, triage-needed]
13+
body:
14+
- type: markdown
15+
attributes:
16+
value: >
17+
This repository hosts the Swift Testing library and its documentation.
18+
It does _not_ track feedback for Xcode and other closed source Apple
19+
developer software such as XCTest; please direct that to
20+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
21+
22+
___
23+
24+
Swift Testing is guided by a community-driven evolution process.
25+
Submitting this form is not a guarantee that the request will be
26+
considered or implemented. If the request implies an addition, removal,
27+
or change to the features of Swift Testing or its public interfaces,
28+
please consider socializing it on the
29+
[Swift forums](https://forums.swift.org/c/related-projects/swift-testing)
30+
instead. The Swift forums are the preferred space for sharing ideas and
31+
discussing them with the Swift community.
32+
- type: textarea
33+
attributes:
34+
label: Motivation
35+
description: >
36+
Describe the problems that this idea seeks to address. If the problem is
37+
that some common pattern is currently hard to express, show how one can
38+
currently get a similar effect and describe its drawbacks. If it's
39+
completely new functionality that cannot be emulated, motivate why this
40+
new functionality would help create better Swift tests.
41+
validations:
42+
required: true
43+
- type: textarea
44+
attributes:
45+
label: Proposed solution
46+
description: >
47+
Describe the proposed solution to the problem. Provide examples and
48+
describe how they work. Show how this solution is better than current
49+
workarounds: is it cleaner, safer, or more efficient?
50+
validations:
51+
required: true
52+
- type: textarea
53+
attributes:
54+
label: Alternatives considered
55+
description: >
56+
Any alternative approaches that were considered, and why the _proposed
57+
solution_ was chosen instead.
58+
validations:
59+
required: false
60+
- type: textarea
61+
attributes:
62+
label: Additional information
63+
description: >
64+
Any complementary information that could be valuable to an author of a
65+
formal proposal, an implementor, or future discussions. For example, a
66+
link to a discussion or post that motivated this request.
67+
validations:
68+
required: false

‎.github/ISSUE_TEMPLATE/03-task.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2025 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
name: ⚙️ Track a task
10+
description: >
11+
Tasks can be used to track internal work, extract individual subtasks from a
12+
larger issue, or can serve as umbrella issues themselves.
13+
labels: []
14+
body:
15+
- type: markdown
16+
attributes:
17+
value: >
18+
This repository hosts the Swift Testing library and its documentation.
19+
It does _not_ track feedback for Xcode and other closed source Apple
20+
developer software such as XCTest; please direct that to
21+
[Feedback Assistant](https://developer.apple.com/bug-reporting) instead.
22+
- type: textarea
23+
attributes:
24+
label: Description
25+
description: >
26+
A comprehensive description of the task, in human language.
27+
validations:
28+
required: true
29+
- type: textarea
30+
attributes:
31+
label: Additional information
32+
description: >
33+
Any complementary information that could be valuable to an implementor.
34+
For example, a link to a discussion or post that motivated this task.
35+
validations:
36+
required: false

‎.github/ISSUE_TEMPLATE/BUG_REPORT.yml‎

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

‎.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml‎

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

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2025 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
blank_issues_enabled: true
10+
contact_links:
11+
- name: 🌐 Discuss an idea
12+
url: https://forums.swift.org/c/related-projects/swift-testing
13+
about: >
14+
Share an idea with the Swift Testing community.
15+
- name: 📄 Formally propose a change
16+
url: https://github.com/swiftlang/swift-testing/blob/main/Documentation/Proposals/0000-proposal-template.md
17+
about: >
18+
Formally propose an addition, removal, or change to the APIs or features
19+
of Swift Testing.
20+
- name: 🙋 Ask a question
21+
url: https://forums.swift.org/c/related-projects/swift-testing
22+
about: >
23+
Ask a question about or get help with Swift Testing. Beginner questions
24+
welcome!
25+
- name: 🪲 Report an issue with Swift Package Manager
26+
url: https://github.com/swiftlang/swift-package-manager/issues/new/choose
27+
about: >
28+
Report an issue with Swift Package Manager, which includes the
29+
"swift test" CLI tool.
30+
- name: 🪲 Report an issue with Apple software using Feedback Assistant
31+
url: https://developer.apple.com/bug-reporting
32+
about: >
33+
Report an issue with Xcode or other closed source Apple developer
34+
software such as XCTest.
35+
- name: 🪲 Report an issue with the VS Code Swift plugin
36+
url: https://github.com/swiftlang/vscode-swift/issues/new/choose
37+
about: >
38+
Report an issue with the Swift plugin for VS Code, which integrates with
39+
Swift Testing.
40+
- name: 📖 Learn about Swift Testing
41+
url: https://swiftpackageindex.com/swiftlang/swift-testing/main/documentation/testing
42+
about: >
43+
Read the official Swift Testing documentation.

0 commit comments

Comments
 (0)