Thank you for being willing to share your feature proposal idea with the EnergyPlus team. This short article provides some tips for creating a strong proposal.
Note that SPAM and advertisement in proposals are completely unacceptable and provide grounds for banning the proposer. If a proposal is found lacking in certain areas as proposed, the moderating team will provide feedback to proposers as to areas of deficiency. Proposers, in turn, will be responsible for submitting comments to revise their proposals to correct any deficiencies. In addition, the user community at large will be able to weigh in with comments/advice/support and votes to express specific interest or to otherwise help push good proposals forward.
Considerations for a Good Feature Proposal
A feature proposal should contain a title that is descriptive and unambiguous, yet concise. All feature proposals must contain a description. That description at minimum should describe the feature/solution. Ideally, it will also indicate the underlying problem the feature/solution solves and what why it is important. As proposals are discussed and revised, they should eventually incorporate some or all of the following characteristics of good proposals:
Context: Not every user is as intimately familiar with every feature of a program. Provide the necessary context for those evaluating your proposal to know what you’re talking about.
The Larger Problem or Need Addressed: A strong proposal solves a new problem or need or solves an existing problem in a better way. Clearly state the problem(s) and/or pain(s) that the proposal addresses in your proposal description. This is optional for first submission but should eventually be specified. Multiple solutions may appear that try to address the same problem.
Proposals Should Be Specific: A proposal can’t be enacted until we have a specific solution. A strong solution can be obtained through open discussion with the user community including discussion of the tradeoffs between different approaches. A proposal that identifies a relevant problem and compelling rationale may spark competing ideas that can be compared and contrasted by the community for an overall better end product.
Pros and Cons: Not everything is awesome. What are the pros and cons of this solution as compared to other options (including the “do nothing” option)?
One Thing at a Time: It is better to break up a large proposal that tackles multiple issues into several smaller proposals. Smaller proposals are easier to enact and gives the proposer a better chance of getting a change into the software. To the extent possible, proposals should be simple in the sense of being independent of one another. If a proposal does depend on another proposal being implemented, it should clearly say so.
New Idea, New Proposal: In the course of discussion, a better solution than originally proposed may present itself. Instead of modifying the solution proposed in the existing idea, a new feature proposal should be submitted which copies work already done to identify the problem and why it’s important in addition to the newly proposed solution.
SMART: Feature proposals must eventually follow the SMART criteria in order to be acted upon: specific, measurable, achievable, relevant, and time-based. Note that the development team will be responsible for determining achievability and timing depending on available resources. Proposers can help by identifying the underlying problem/need (which speaks to “relevance”) and being specific with their proposed solution (which helps determine the other SMART metrics).
Feature vs Bug Fix
In essence, a bug report is when some feature
X does not work as intended assuming the program’s intention and design are sound.
In contrast, a good feature proposal will argue that the software should have feature
A (or that existing feature
A should work differently than it currently does) to (better) solve problem
B for reasons
Thus, feature proposals are about proposing solutions for unaddressed problems or for solving existing problems better; proposing features improves design quality and software scope. In contrast, bug reports address errors in implementation; reporting bugs improves implementation quality.
Feature Proposal Template
Following is a feature proposal template. The information listed below can be typed into the idea proposal description box with the title information corresponding to an idea’s title. Initially, a feature request must at least have a title and description listing the proposed solution/feature. Identification of the underlying problem addressed by the solution/feature is encouraged but not necessary on initial proposal.
The suggested syntax for a fully written out description block appears below followed by a more in-depth description of each section:
Problem: Succinct statement of the underlying problem or need addressed. Rationale: Why it's important to address the given problem. Solution: Your proposed solution. Succinct yet specific. Context: A brief background for those who may not be familiar. May include links to other resources Pros and Cons of Solution: + 'pro' statement 1 + 'pro' statement 2 - 'con' statement 1 - 'con' statement 2
Title: Proposal Title
Choose a succinct, yet sufficiently descriptive title. Try above all else to differentiate your proposal title from others that already exist.
Problem – The “Why”
State what problem(s), need(s), or pain(s) your proposed feature is supposed to address. Why is your feature needed and what issues or desires drove you to propose it? Why are they important? This section is not required when submitting ideas but should be one of the first points of comment discussion. This section, if present, should appear first and should be preceded by the text: “Problem:”. Optionally, you may also argue why it is important to address the given problem in a section titled: “Rationale:”.
Solution/Feature – The “What” (required)
Propose a clear, specific solution to the problem(s)/need(s) you mention above through a description of your feature. Multiple feature ideas should each get their own proposal. This section must be present and should appear in the idea description preceded by the text: “Solution:”.
Provide sufficient background and context for a typical user to understand your proposal if necessary. Although you are welcome to provide links to other resources, a succinct, self-contained context is often well received. This section, if present, should appear in the idea description preceded by the text: “Context:”.
Pros and Cons
Administrators will periodically summarize the pros and cons of the solution as appear in the comments thread. This is optional for an initial submittal.