diff --git a/.github/ISSUE_TEMPLATE/01-bug-report.yml b/.github/ISSUE_TEMPLATE/01-bug-report.yml new file mode 100644 index 00000000..46dfc46c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01-bug-report.yml @@ -0,0 +1,72 @@ +name: Bug report +description: Something in kotlinx-datetime behaves incorrectly +title: "[Bug] " +labels: + - bug + +body: + - type: markdown + attributes: + value: | + Thanks for the report! + + Please focus on **what happens** and **how to reproduce it**. + Everything else is optional. + + Before filing, a quick sanity check (no worries if you're unsure): + + - If the behavior is documented but feels wrong or questionable, + it might be better filed as a **design discussion** rather than a bug. + - If something is unclear rather than broken, you may get a faster answer on + [StackOverflow](https://stackoverflow.com/) or in the [Kotlin Slack](https://slack-chats.kotlinlang.org/). + - Please make sure the issue is in **kotlinx-datetime itself**, + not in Kotlin, platform date/time APIs, or your own code. + - If you suspect this might already be fixed, trying a recent version can help — + but it's okay if you can't. + + If in doubt, just file the issue and describe what you see. + + - type: textarea + id: problem + attributes: + label: What is happening? What should have happened instead? + placeholder: | + Describe what looks wrong or unexpected in date/time operations. + validations: + required: true + + - type: textarea + id: reproducer + attributes: + label: Reproducer + description: | + Any form of reproducer is welcome. + + - A minimal, self-contained snippet is ideal + - A small sample project is great + - A real-world project or production code is also fine if isolating the issue is hard + + If the code is private, please mention that — we can discuss alternatives. + placeholder: | + ```kotlin + import kotlinx.datetime.* + import kotlin.time.Clock + + fun main() { + val currentMoment = Clock.System.now() + val datetimeInUtc = currentMoment.toLocalDateTime(TimeZone.UTC) + // unexpected behavior here + } + ``` + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Anything else? (optional) + placeholder: | + What you expected, kotlinx-datetime version, Kotlin version, platform (JVM/JS/Native), + time zone information, locale, logs, error messages — whatever you think matters. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/02-feature-request.yml b/.github/ISSUE_TEMPLATE/02-feature-request.yml new file mode 100644 index 00000000..21fd7874 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02-feature-request.yml @@ -0,0 +1,87 @@ +name: Feature request +description: Suggest a new feature or enhancement for kotlinx-datetime +title: "[Feature] " +labels: + - enhancement + +body: + - type: markdown + attributes: + value: | + Thanks for the idea! + + Please focus on **what problem you're trying to solve** and **why existing APIs don't work well enough**. + + If you're unsure whether this is kotlinx-datetime-related, consider asking on [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlinx-datetime) or the [Kotlinlang Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) first — the functionality may already exist elsewhere, or someone may recommend an alternative. + + - type: textarea + id: use_case + attributes: + label: What are you trying to do? + description: | + Describe the problem or use case you're facing. + Focus on *what* you want to achieve and *why* it's difficult today. + placeholder: | + Example: + I need to work with business days and holidays, + and I need to ... + validations: + required: true + + - type: textarea + id: underlying_problem + attributes: + label: What problem does this actually solve? + description: | + Describe the underlying need, independent of any specific solution or API. + + In other words: + * What is hard or impossible to do today? + * What breaks or becomes unsafe/inefficient without this? + * How would you know that the problem is solved? + + Please avoid describing a specific function or API here. + placeholder: | + Example: + In production we need to handle recurring events across time zones... + Without this, we end up with... + Existing APIs fail because... + validations: + required: true + + - type: textarea + id: idea + attributes: + label: Your idea (optional) + description: | + If you have an idea of what the solution or API could look like, feel free to share it. + Rough sketches, pseudocode, or examples are all welcome. + placeholder: | + ```kotlin + fun LocalDateTime.withBusinessDays(days: Int): LocalDateTime + ``` + validations: + required: false + + - type: textarea + id: prior_art + attributes: + label: Prior art or similar ideas (optional) + description: | + Are there similar features in other date/time libraries or ecosystems? + Links and comparisons are helpful, but not required. + placeholder: | + Java's java.time has a similar feature that works like this... + Temporal.js uses an approach where... + validations: + required: false + + - type: textarea + id: additional + attributes: + label: Anything else? (optional) + description: | + Motivation, constraints, production experience, trade-offs — + anything that helps understand the request. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/03-design-considerations.yml b/.github/ISSUE_TEMPLATE/03-design-considerations.yml new file mode 100644 index 00000000..c9d67b9f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03-design-considerations.yml @@ -0,0 +1,84 @@ +name: Design consideration +description: Discuss intentional but suboptimal behavior or possible design improvements +title: "[Design] " +labels: + - design + +body: + - type: markdown + attributes: + value: | + This issue type is for discussing **intentional library behavior that feels suboptimal**, + surprising, or worth reconsidering. + + If the behavior looks unintentional, undocumented, or plainly wrong, + a **Bug report** might be a better fit. + + If you're unsure — just describe what you see and why it feels off. + + For quick questions or general design advice, you may also want to ask on + [StackOverflow](https://stackoverflow.com/) or in the + [Kotlin Slack](https://slack-chats.kotlinlang.org/). + + - type: textarea + id: current + attributes: + label: What do we have today? + description: | + Describe the current behavior. + Code examples are very helpful. + placeholder: | + Currently, this behaves like: + ```kotlin + // example + ``` + validations: + required: true + + - type: textarea + id: concern + attributes: + label: Why does this feel problematic? + description: | + What is suboptimal, awkward, or limiting about the current behavior? + placeholder: | + This makes it hard to... + The current API is confusing when... + validations: + required: true + + - type: textarea + id: idea + attributes: + label: Possible alternative (optional) + description: | + If you have an idea of how this could work differently, feel free to share it. + This can be vague, incomplete, or exploratory. + placeholder: | + It might be nicer if... + ```kotlin + // sketch + ``` + validations: + required: false + + - type: textarea + id: tradeoffs + attributes: + label: Trade-offs you see (optional) + description: | + Any pros, cons, risks, or breaking-change concerns you already thought about. + Not required, but very welcome. + placeholder: | + One concern is that this could... + validations: + required: false + + - type: textarea + id: additional + attributes: + label: Anything else? (optional) + description: | + Context, links to prior discussions, production experience, or related issues. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/04-release-candidate-feedback.yml b/.github/ISSUE_TEMPLATE/04-release-candidate-feedback.yml new file mode 100644 index 00000000..553d4119 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/04-release-candidate-feedback.yml @@ -0,0 +1,59 @@ +name: Release candidate feedback +description: Report a regression or issue found in a Release Candidate +title: "RC: " +labels: + - bug + +body: + - type: markdown + attributes: + value: | + Thanks for testing a Release Candidate! + + If something broke or started behaving differently in an RC, + please let us know as soon as possible. + + If you're not 100% sure whether this also happens in the latest stable release, + that's okay — still file the issue and describe what you see. + + - type: textarea + id: problem + attributes: + label: What broke or changed? + description: | + Describe the observed behavior. + Even a rough description is helpful. + placeholder: | + After updating to the RC, I noticed that... + validations: + required: true + + - type: textarea + id: reproducer + attributes: + label: Reproducer (optional) + description: | + Any form of reproducer is welcome. + + - A minimal, self-contained snippet is ideal + - A small sample project is great + - A real-world project or production code is also fine if isolating the issue is hard + + If the code is private, please mention that — we can discuss alternatives. + placeholder: | + ```kotlin + // example + ``` + + or a link to a repository / project + validations: + required: false + + - type: textarea + id: additional + attributes: + label: Anything else? (optional) + description: | + Versions, environment details, logs, or anything that might help. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..a4f65b1a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: 💬 Kotlinlang Slack + url: https://surveys.jetbrains.com/s3/kotlin-slack-sign-up + about: Ask questions, share knowledge, and discuss kotlinx-datetime usage with the community