From 09067e694997aed6cabc969f312c1938001e50e8 Mon Sep 17 00:00:00 2001 From: Chaoren Lin Date: Mon, 16 Oct 2023 16:08:01 -0700 Subject: [PATCH] Add some issue and PR templates for Guava. RELNOTES=n/a PiperOrigin-RevId: 573957446 --- .github/ISSUE_TEMPLATE/bug_report.yaml | 84 ++++++++++ .../feature_addition_request.yaml | 156 ++++++++++++++++++ .../feature_enhancement_request.yaml | 144 ++++++++++++++++ .github/pull_request_template.md | 12 ++ 4 files changed, 396 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yaml create mode 100644 .github/ISSUE_TEMPLATE/feature_addition_request.yaml create mode 100644 .github/ISSUE_TEMPLATE/feature_enhancement_request.yaml create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml new file mode 100644 index 000000000000..9070b80fe14d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -0,0 +1,84 @@ +name: Bug Report +description: Something is not working as expected +labels: ["type=defect"] +body: + - type: markdown + attributes: + value: > + Thank you so much for wanting to contribute to Guava! + + + Telling us about a bug is possibly the single most valuable contribution you can make to + Guava, so thank you for this bug report! + + - type: textarea + attributes: + label: Description + description: Please describe the issue. + validations: + required: true + + - type: textarea + attributes: + label: Example + description: > + Please provide a [Short, Self Contained, Correct (Compilable), Example](http://sscce.org/) + demonstrating the bug. + validations: + required: true + + - type: textarea + attributes: + label: Expected Behavior + description: What did you expect to happen? + validations: + required: true + + - type: textarea + attributes: + label: Actual Behavior + description: What actually happened? + validations: + required: true + + - type: dropdown + attributes: + label: Packages + description: If this issue is package-specific, then please select the relevant packages. + multiple: true + options: + - com.google.common.annotations + - com.google.common.base + - com.google.common.cache + - com.google.common.collect + - com.google.common.escape + - com.google.common.eventbus + - com.google.common.graph + - com.google.common.hash + - com.google.common.io + - com.google.common.math + - com.google.common.net + - com.google.common.primitives + - com.google.common.reflect + - com.google.common.testing + - com.google.common.util.concurrent + + - type: dropdown + attributes: + label: Platforms + description: If this issue is platform-specific, then please select the relevant platforms. + multiple: true + options: + - Android + - GWT + - Java 8 + - Java 11 + - Java 17 + + - type: checkboxes + attributes: + label: Code of Conduct + options: + - label: > + I agree to follow the [code of conduct](../../.github/blob/master/CODE_OF_CONDUCT.md). + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_addition_request.yaml b/.github/ISSUE_TEMPLATE/feature_addition_request.yaml new file mode 100644 index 000000000000..995b6e2f5d5f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_addition_request.yaml @@ -0,0 +1,156 @@ +name: Feature Addition Request +description: I want to add a new feature +labels: ["type=addition"] +body: + - type: markdown + attributes: + value: > + Thank you so much for wanting to contribute to Guava! + + + Filing feature requests is one of the most popular ways to contribute to Guava. + + + Be aware, though: most feature requests are not accepted, even if they're suggested by + a full-time Guava team member. [Feedback](http://stackoverflow.com/a/4543114/869736) + from our users indicates that they really appreciate Guava's high power-to-weight ratio. + It's important to us to keep Guava as easy to pick up and understand as we can. That means + boiling features down to compact but powerful abstractions, and controlling feature bloat + carefully. + + + Guava's main yardstick for evaluating proposed features can be summed up as + [utility times ubiquity](../wiki/PhilosophyExplained#utility-times-ubiquity). + + + #### Utility: compare with alternatives + + + There is always some alternative to adding this new feature to Guava, even if it's just + forking Guava yourself. + + + We want to see that new features have some significant advantage over the alternatives. + These advantages can take [many forms](../wiki/PhilosophyExplained#utility), but taking the + time to discuss them in detail will make it much clearer why this feature should be added to + Guava. + + + What helps the most is to have the following laid out clearly: + + - type: textarea + attributes: + label: 1. What are you trying to do? + validations: + required: true + + - type: textarea + attributes: + label: 2. What's the best code you can write to accomplish that without the new feature? + validations: + required: true + + - type: textarea + attributes: + label: 3. What would that same code look like if we added your feature? + validations: + required: true + + - type: markdown + attributes: + value: > + Having the two approaches to a use case side by side can make it much easier to pick out the + differences between them. + + + Additionally, it's very useful to us if you can provide a "straw API" — what the + method signatures would look like, for example, even if the method and class names are still + in flux. This can make the feature you're suggesting much clearer to us. + + - type: textarea + attributes: + label: What would the method signatures look like? + placeholder: | + e.g., + public static ImmutableList of(); + public static ImmutableList of(E element); + public static ImmutableList of(E e1, E e2); + ... + render: java + validations: + required: false + + - type: markdown + attributes: + value: > + #### Ubiquity: provide concrete use cases + + + Did you actually encounter the need for this feature in a real-world scenario, or is it just + a feature that seems like a sensible addition to Guava? + + + Before new features get added to Guava, we really want to be sure that it's a use case that + actually comes up in the real world. We want to hear the real-world use case so the + community can discuss and debate whether this feature is actually the best way to address + the real use case, or whether or not a different abstraction might be appropriate. + + + It's okay that you can't always give us complete context on a use case. Not all of you are + at liberty to discuss the details of what you're working on. + + + But Guava aims to provide features that are useful across boundaries of projects, companies, + or even industries — utilities useful for a sizable proportion of all Java programmers + everywhere. If you can give enough detail such that any of us can imagine coming across + a similar need in our own work, that's extremely helpful in studying how broadly useful the + feature will be. + + - type: textarea + attributes: + label: Concrete Use Cases + description: Please provide use cases that actually came up in the real world. + validations: + required: true + + - type: dropdown + attributes: + label: Packages + description: Please select all of the packages that are relevant to this feature request. + multiple: true + options: + - com.google.common.annotations + - com.google.common.base + - com.google.common.cache + - com.google.common.collect + - com.google.common.escape + - com.google.common.eventbus + - com.google.common.graph + - com.google.common.hash + - com.google.common.io + - com.google.common.math + - com.google.common.net + - com.google.common.primitives + - com.google.common.reflect + - com.google.common.testing + - com.google.common.util.concurrent + + - type: checkboxes + attributes: + label: Required Readings + options: + - label: > + I agree to follow the [code of conduct](../../.github/blob/master/CODE_OF_CONDUCT.md). + required: true + - label: > + I have read and understood the + [contribution guidelines](../wiki/HowToContribute#feature-requests). + required: true + - label: > + I have read and understood [Guava's philosophy](../wiki/PhilosophyExplained), and + I strongly believe that this feature aligns with it. + required: true + - label: > + I have visited the [idea graveyard](../wiki/IdeaGraveyard), and did not see anything + similar to this idea. + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_enhancement_request.yaml b/.github/ISSUE_TEMPLATE/feature_enhancement_request.yaml new file mode 100644 index 000000000000..5509729cad91 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_enhancement_request.yaml @@ -0,0 +1,144 @@ +name: Feature Enhancement Request +description: Suggest an improvement to an existing feature +labels: ["type=enhancement"] +body: + - type: markdown + attributes: + value: > + Thank you so much for wanting to contribute to Guava! + + + Filing feature requests is one of the most popular ways to contribute to Guava. + + + Be aware, though: most feature requests are not accepted, even if they're suggested by + a full-time Guava team member. [Feedback](http://stackoverflow.com/a/4543114/869736) + from our users indicates that they really appreciate Guava's high power-to-weight ratio. + It's important to us to keep Guava as easy to pick up and understand as we can. That means + boiling features down to compact but powerful abstractions, and controlling feature bloat + carefully. + + - type: input + attributes: + label: Existing API + description: Which existing class or method do you want to improve? + placeholder: e.g., `com.google.common.collect.ImmutableList::of` + validations: + required: true + + - type: markdown + attributes: + value: > + Guava's main yardstick for evaluating proposed features can be summed up as + [utility times ubiquity](../wiki/PhilosophyExplained#utility-times-ubiquity). + + + #### Utility: compare with alternatives + + + There is always some alternative to adding this new feature to Guava, even if it's just + forking Guava yourself. + + + We want to see that new features have some significant advantage over the alternatives. + These advantages can take [many forms](../wiki/PhilosophyExplained#utility), but taking the + time to discuss them in detail will make it much clearer why this feature should be added to + Guava. + + + What helps the most is to have the following laid out clearly: + + - type: textarea + attributes: + label: 1. What are you trying to do? + validations: + required: true + + - type: textarea + attributes: + label: 2. What's the best code you can write to accomplish that without the new feature? + validations: + required: true + + - type: textarea + attributes: + label: 3. What would that same code look like if we added your feature? + validations: + required: true + + - type: markdown + attributes: + value: > + Having the two approaches to a use case side by side can make it much easier to pick out the + differences between them. + + + Additionally, it's very useful to us if you can provide a "straw API" — what the + method signatures would look like, for example, even if the method and class names are still + in flux. This can make the feature you're suggesting much clearer to us. + + - type: textarea + attributes: + label: What would the method signatures look like? + placeholder: | + e.g., + public static ImmutableList of(); + public static ImmutableList of(E element); + public static ImmutableList of(E e1, E e2); + ... + render: java + validations: + required: false + + - type: markdown + attributes: + value: > + #### Ubiquity: provide concrete use cases + + + Did you actually encounter the need for this feature in a real-world scenario, or is it just + a feature that seems like a sensible addition to Guava? + + + Before new features get added to Guava, we really want to be sure that it's a use case that + actually comes up in the real world. We want to hear the real-world use case so the + community can discuss and debate whether this feature is actually the best way to address + the real use case, or whether or not a different abstraction might be appropriate. + + + It's okay that you can't always give us complete context on a use case. Not all of you are + at liberty to discuss the details of what you're working on. + + + But Guava aims to provide features that are useful across boundaries of projects, companies, + or even industries — utilities useful for a sizable proportion of all Java programmers + everywhere. If you can give enough detail such that any of us can imagine coming across + a similar need in our own work, that's extremely helpful in studying how broadly useful the + feature will be. + + - type: textarea + attributes: + label: Concrete Use Cases + description: Please provide use cases that actually came up in the real world. + validations: + required: true + + - type: checkboxes + attributes: + label: Required Readings + options: + - label: > + I agree to follow the [code of conduct](../../.github/blob/master/CODE_OF_CONDUCT.md). + required: true + - label: > + I have read and understood the + [contribution guidelines](../wiki/HowToContribute#feature-requests). + required: true + - label: > + I have read and understood [Guava's philosophy](../wiki/PhilosophyExplained), and + I strongly believe that this feature aligns with it. + required: true + - label: > + I have visited the [idea graveyard](../wiki/IdeaGraveyard), and did not see anything + similar to this idea. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000000..18fa1c7a080c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,12 @@ +