1name: Feature Addition Request 2description: I want to add a new feature 3labels: ["type=addition"] 4body: 5 - type: markdown 6 attributes: 7 value: > 8 Filing feature requests is one of the most popular ways to contribute to Guava. 9 10 11 Be aware, though: most feature requests are not accepted, even if they're suggested by 12 a full-time Guava team member. [Feedback](https://stackoverflow.com/a/4543114) from our 13 users indicates that they really appreciate Guava's high power-to-weight ratio. It's 14 important to us to keep Guava as easy to use and understand as we can. That means boiling 15 features down to compact but powerful abstractions, and controlling feature bloat carefully. 16 17 18 Guava's main yardstick for evaluating proposed features can be summed up as [utility times 19 ubiquity](https://github.com/google/guava/wiki/PhilosophyExplained#utility-times-ubiquity). 20 21 22 #### Utility: compare with alternatives 23 24 25 There is always *some* alternative to adding a new feature to Guava, even if it's just 26 forking Guava yourself. 27 28 29 We want to see that new features have some significant advantage over the alternatives. 30 These advantages can take 31 [many forms](https://github.com/google/guava/wiki/PhilosophyExplained#utility), but taking 32 the time to discuss them in detail will make it much clearer why this feature should be 33 added to Guava. 34 35 36 Please fill out the following fields to give us a better understanding of your proposed 37 feature and its potential value for other Guava users. 38 39 - type: textarea 40 attributes: 41 label: 1. What are you trying to do? 42 validations: 43 required: true 44 45 - type: textarea 46 attributes: 47 label: 2. What's the best code you can write to accomplish that without the new feature? 48 validations: 49 required: true 50 51 - type: textarea 52 attributes: 53 label: 3. What would that same code look like if we added your feature? 54 validations: 55 required: true 56 57 - type: markdown 58 attributes: 59 value: > 60 Comparing two approaches to a use case side by side can make it easier to examine the 61 differences between them. 62 63 64 Additionally, it's very useful to us if you can provide a "straw API" — what the 65 method signatures would look like, for example, even if the method and class names are still 66 in flux. This can make the feature you're suggesting much clearer to us. 67 68 - type: textarea 69 attributes: 70 label: (Optional) What would the method signatures for your feature look like? 71 placeholder: | 72 e.g., 73 public static <E> ImmutableList<E> of(); 74 public static <E> ImmutableList<E> of(E element); 75 public static <E> ImmutableList<E> of(E e1, E e2); 76 ... 77 render: java 78 validations: 79 required: false 80 81 - type: markdown 82 attributes: 83 value: > 84 #### Ubiquity: provide concrete use cases 85 86 87 Did you *actually* encounter the need for this feature in a real-world scenario, or is it 88 just a feature that seems like a sensible addition to Guava? 89 90 91 Before new features get added to Guava, we really want to be sure that it's for a use case 92 that actually comes up in the real world. We want to hear the real-world use case so the 93 community can discuss and debate whether this feature is actually the *best* way to address 94 the real use case, or whether or not a different abstraction might be more appropriate. 95 96 97 It's okay if you can't provide complete context on a use case. We understand if you are not 98 able to discuss the full details of what you're working on. 99 100 101 But Guava aims to provide features that are useful across boundaries of projects, companies, 102 or even industries — utilities useful for a sizable proportion of all Java programmers 103 everywhere. If you can give enough detail such that any of us can imagine coming across 104 a similar need in our own work, that's extremely helpful in studying how broadly useful the 105 feature will be. 106 107 - type: textarea 108 attributes: 109 label: Concrete Use Cases 110 description: Please provide use cases that actually came up in the real world. 111 validations: 112 required: true 113 114 - type: dropdown 115 attributes: 116 label: Packages 117 description: Please select all of the packages that are relevant to this feature request. 118 multiple: true 119 options: 120 - com.google.common.annotations 121 - com.google.common.base 122 - com.google.common.cache 123 - com.google.common.collect 124 - com.google.common.escape 125 - com.google.common.eventbus 126 - com.google.common.graph 127 - com.google.common.hash 128 - com.google.common.io 129 - com.google.common.math 130 - com.google.common.net 131 - com.google.common.primitives 132 - com.google.common.reflect 133 - com.google.common.testing 134 - com.google.common.util.concurrent 135 136 - type: checkboxes 137 attributes: 138 label: Checklist 139 options: 140 - label: > 141 I agree to follow the 142 [code of conduct](https://github.com/google/.github/blob/master/CODE_OF_CONDUCT.md). 143 required: true 144 - label: > 145 I have read and understood the [contribution 146 guidelines](https://github.com/google/guava/wiki/HowToContribute#feature-requests). 147 required: true 148 - label: > 149 I have read and understood 150 [Guava's philosophy](https://github.com/google/guava/wiki/PhilosophyExplained), and 151 I strongly believe that this proposal aligns with it. 152 required: true 153 - label: > 154 I have visited the [idea graveyard](https://github.com/google/guava/wiki/IdeaGraveyard), 155 and did not see anything similar to this idea. 156 required: true 157