git.iko.soy/elk
on 63243ca help sign in
elk/How to Request Features.md
93 lines 4.9 kB history raw
1# How to make a Feature Request
3Adding features is hard work and has long term implications for Elm.
4If you think your particular feature is important, help make it happen
5by doing some of the background work that goes into actually adding it.
7### Before making a Request / Formatting:
9 - Make sure your feature has not already been requested. Look through the
10 email list to find similar requests.
11 - Submit feature requests by emailing the list. This allows the broadest
12 discussion and does not clutter up the GitHub repository with speculative
13 issues. I'd prefer to use the GitHub issue tracker for bug tracking and
14 issues with the existing code base.
15 - Label all feature requests with a subject like "Request: _____". For
16 example, if you want to be the umpteenth person to request type classes,
17 you would use the subject "Request: Type Classes".
19### Body of the Request:
21Your request should address all of the following issues:
23**General Problem:** Clearly define the purpose of adding the feature.
24What general problem do you want to solve? Why is that problem important?
25Why is it important for a functional GUI language?
27**Specific Use-Cases:** What are the specific cases when the general problem
28is actually an issue? How often does this case come up? Why are these cases
29important to easily designing graphical user interfaces? Why are existing
30solutions in Elm unsuitable?
32**Background Materials:** Are there relevant papers on the topic? Are there
33languages or libraries that already have this feature? Organize this material
34and provide a concise and helpful overview.
36**Alternatives:** What are all the ways to address the general problem or a
37closely related problem? For example, the semantic flexibility of type classes
38can be largely replicated with a module system in the style of ML.
39What are the strengths and weakness of each of the alternative solutions?
41**Suggested Approach:** Outline your specific approach. How does it address
42the general problem? How does it work? How hard is it going to be to add?
43What other language features does it depend on that need to be added first?
44Try to take a look at the relevant code to see if it would require significant
45changes. If you are suggesting an API or library changes, include an interface
46(a list of type signatures) for the functions you would like to add (perhaps
47multiple interfaces if there are many good approaches).
49**Known Issues:** Search for issues that people have already found. Think of
50any other possible downside and list them too. For example, one downside of
51typeclasses is that they are globally defined for each type, so you cannot
52have multiple `Ord` instances for Strings. This can lead to namespace pollution
53within a project. In general you can only implement an "interface" once per
54type, so it is very tricky to get the flexibility of ML's module functors.
56**Justification:** Why is the added complexity of your feature worth it? Discuss
57both implementation complexity in the compiler, and conceptual complexity that
58users must deal with. Why is your feature better than the alternative solutions?
59Why is it okay to ignore the known issues? Is there any way to overcome the known
60issues? Will it be difficult or confusing for users coming from JavaScript?
62### Some final notes:
64If for some reason you cannot provide details for some of these categories,
65explain why the category is not applicable.
67Re-read before posting. Is your request constructive? Is it well organized?
68Are there any details you forgot? Can anything be clarified or trimmed down?
69Considering a request takes time, so be considerate about how much work a
70reader has to do to take it seriously.
72A feature request is not an opportunity to be sassy or glib. Try to present
73the information and argument clearly, concisely, thoroughly, and in an unbiased
74manner.
76This is likely to be an iterative process. People will have comments and
77questions. Everyone please be kind. Commenters, if you think you have a
78concern, raise it as a question: "But what happens when you do blah?" instead
79of "This will break when you do blah". Assume you have misunderstood their
80proposal or only have a shallow understanding of it. Seek clarification, not victory.
82Comments are not a place for flame wars. Discuss specific issues. Vague
83complaining and unsupported claims should either be forgotten or developed
84into specific and well-supported concerns.
86I am always working hard to add cool stuff to Elm, and it is a lot of work.
87I must prioritize issues to focus on the things that have the highest impact
88for improving the quality of Elm, addressing the concerns of current users,
89and making Elm more appealing for new users. I do not have infinite time,
90so some things must receive more attention than others. I apologize in advance.
92And to summarize, just be cool! I want Elm to be really fun and easy to use,
93and I want your projects to be amazing!