Java

1
name: Feature Addition Request
2
description: I want to add a new feature
3
labels: ["type=addition"]
4
body:
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 &mdash; 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