New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HEP: a hledger proposals process #462

simonmichael opened this Issue Jan 7, 2017 · 2 comments


None yet
1 participant

simonmichael commented Jan 7, 2017

HEP is an optional lightweight format/process for hledger-related proposals. Use it as a mental checklist to evaluate new projects, to communicate ideas, to give wishlist issues more substance, to build consensus for major changes, etc. Goals:

  • clarify proposals/costs/benefits/priority early and more cheaply
  • produce effective, end-user-focussed designs
  • avoid wasted work
  • improve project productivity.

You can jump here via

Current HEP process:

An official HEP is an issue in the issue tracker with a HEP: prefix in the title and including answers to most of the questions below, or questions quite like them. For a less formal or draft proposal, you could use RFC: or no prefix instead.

If the proposal evolves, the latest version should be clearly visible (inline or linked) at the top of the issue.

Here are the HEP questions, ready for copy/paste into a new issue.

### What is being [proposed](, in one sentence ?

### What real problem is being solved ?

### What is the proposed UI and help, if applicable ?

### What is a rough draft of the reference documentation, or other details ?

### How will this interact with existing features and systems ?

### How will we test or ensure this remains effective ?

### What is in and out of scope ?

### What is an estimate of developer hours required ?

### Which of our current [Projects]( does this relate to ?

### Discussion

Here is the original HEP proposal:

What is a one-sentence explanation of this ?

A standard format/guide for an optional more organised style of enhancement requests and proposals which might be useful for us in the hledger project.

What real problem does this solve, and for whom ?

For developers and feature proposers, a standard checklist and format for planning and proposing new projects could encourage early clarity around goals, benefits, costs, UI, docs, etc. This would facilitate clear communication, efficient discussion, and identification of major problems early. In particular, it should help reduce the danger of contributors doing a bunch of work that does not get merged, or of folks like me diving into a lengthy gold-plated development task without sufficiently clarifying its real value and priority.

What is a mockup of the UI and help for this (if applicable) ?

Questions and format similar to this first HEP, to be used in new issues or in mail list discussions when helpful.

What is a rough draft of the reference docs ?

When considering or proposing a new hledger feature, development task, process, etc. - eg when opening a wishlist issue or making a proposal on the mail list - to clarify and give it more impact you can choose to follow HEP style. A HEP includes some standard questions and answers which help communicate the purpose and value of the proposal. An official HEP is a new issue in the issue tracker following this style, with a HEP: prefix in the title. A HEP's number is its issue number (HEP numbers are not consecutive). A regular issue could be converted to a HEP and vice versa. Discussion takes place on the issue, or references the issue/HEP number. As a HEP evolves, new answers can be posted as comments, or the original issue description can be edited. The approach will evolve as needed.

How will we test / ensure this remains effective ?

What is in/out of scope for this ?

What is an estimate of hours required ?

More details ?

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.


This comment has been minimized.


simonmichael commented Jan 15, 2017

Revised, accessible via


This comment has been minimized.


simonmichael commented Feb 4, 2017


@simonmichael simonmichael changed the title from HEP: an optional semi-structured proposals process to HEP: a hledger proposals process Feb 4, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment