From 30db6be69682186714b5635839dbdc3b8e7558bf Mon Sep 17 00:00:00 2001
From: Dmitry Khalanskiy <52952525+dkhalanskyjb@users.noreply.github.com>
Date: Tue, 27 Dec 2022 15:56:17 +0300
Subject: [PATCH] Add issue templates

---
 .github/ISSUE_TEMPLATE/bug_report.md          | 29 ++++++++++++
 .../ISSUE_TEMPLATE/design-considerations.md   | 46 +++++++++++++++++++
 .github/ISSUE_TEMPLATE/feature_request.md     | 33 +++++++++++++
 3 files changed, 108 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/design-considerations.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000000..0fa80d1f86
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Our code behaves incorrectly?
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+<!--
+**Double-check**
+
+* Is this *really* a bug?
+  - If the behavior is documented, but you disagree with it, please do file an issue, but as a "Design consideration," not a "Bug report."
+  - If you don't understand why something behaves the way it does, consider asking on [StackOverflow](https://stackoverflow.com/) or the [Kotlin Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). The community is active and will likely clarify everything better than we could!
+* Is the problem not in some third-party library, not in [Kotlin](kotl.in/issue), or your own code—is it in the `kotlinx.coroutines` library itself?
+  - Example: you write for Android, and your code works properly on most devices, but for a couple of them, it fails. Then please direct this to Google and/or the manufacturer of your device.
+* Maybe you're using some ancient version, and the problem doesn't happen with the latest releases of the compiler and the library?
+-->
+
+**Describe the bug**
+
+What happened? What should have happened instead?
+
+**Provide a Reproducer**
+
+* If possible, please provide a small self-contained project (or even just a single file) where the issue reproduces.
+* If you can't pinpoint the issue, please provide at least *some* project where this reproduces, for example, your production one. If you are not ready to show the project publicly, we are open to discussing the details privately.
+* If you really can't provide any code, please do still open an issue. This may prompt other people to chime in with their reproducers.
diff --git a/.github/ISSUE_TEMPLATE/design-considerations.md b/.github/ISSUE_TEMPLATE/design-considerations.md
new file mode 100644
index 0000000000..2ea78332a2
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/design-considerations.md
@@ -0,0 +1,46 @@
+---
+name: Design considerations
+about: We didn't think things through?
+title: ''
+labels: design
+assignees: ''
+
+---
+
+<!--
+This is a place for issue reports that are not exactly bugs (wrong unintentional behavior) but for our library behaving suboptimally (though this could have been intentional).
+
+**Double-check**
+
+* If the behavior is strange, surprising, and undocumented, it could be a good idea to file a "Bug report" instead.
+* Is this still relevant with the latest version of the library? We could have changed this already.
+* Maybe there are good reasons for the existing behavior. Please try searching for existing discussions of the problem.
+* Are you using the right abstraction? Consider asking on [StackOverflow](https://stackoverflow.com/) or the [Kotlin Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). Maybe your need is better solved by some other abstraction entirely.
+
+**Disagreements**
+-->
+
+**What do we have now?**
+
+Preferably with specific code examples.
+
+**What should be instead?**
+
+Preferably with specific code examples.
+
+**Why?**
+
+The upsides of your proposal.
+* Who would benefit from this and how?
+  - Would it be possible to cover new use cases?
+  - Would some code become clearer?
+  - Would the library become conceptually simpler?
+  - etc.
+
+**Why not?**
+
+The downsides of your proposal that you already see.
+* Is this a breaking change?
+* Are there use cases that are better solved by what we have now?
+* Does some code become less clear after this change?
+* etc.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000000..beb1f5e5c3
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: We're missing something?
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+**Double-check**
+
+* Maybe this feature is already here?
+  - Did you check the latest version of the library?
+  - Maybe it's in a form you didn't expect? Consider asking on [StackOverflow](https://stackoverflow.com/) or the [Kotlin Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). The community will likely come up with some code that solves your need, and faster than it would take us to answer the issue!
+* Do you actually *need* this feature? Maybe restructuring your code would neatly eliminate the problem the feature would be solving.
+* Is the coroutines library the best place for this feature? Maybe it would be better suited for some third-party library?
+-->
+
+**Use case**
+
+Explain what *specifically* you are trying to do and why.
+- Example: "I have a `SharedFlow<Double>` that represents readings from an external device. The readings arrive in a set interval of 100 milliseconds. However, I also need to be able to calibrate the state of the external device by setting the readings from inside the program. When I set the state, the `SharedFlow<Double>` must immediately emit the value that was set and ignore any values coming from the device in the following 10 milliseconds since they are considered outdated, as the device is only guaranteed to recalibrate to the updated value after that period."
+- Non-example: "I have a `SharedFlow<T>` that has several sources of its values, and these sources need to have priorities attached to them so that one source always takes precedence over the other in a close race."
+- Non-example: "RxJava has feature X, so the coroutines library should also."
+
+**The Shape of the API**
+
+What could the desired API look like? What would some sample code using the new feature look like?
+
+**Prior Art**
+
+(Optional) Maybe you have seen something like the feature you need, but in other libraries, or there is something very similar but not quite sufficient in `kotlinx.coroutines`?