hledger/NOTES

hledger project notes

"...simplicity of design was the most essential, guiding principle.
Clarity of concepts, economy of features, efficiency and reliability of
implementations were its consequences." --Niklaus Wirth

"The competent programmer is fully aware of the limited size of his own
skull. He therefore approaches his task with full humility, and avoids
clever tricks like the plague." --Edsger Dijkstra

We aim to make reliable, maintainable, usable software, sustainably.
- pair programming
- test-driven development
- fixes, docs, packaging, testing before features
- "bugs" are "errors", as in "the programmer messed up"
- test continuously and thoroughly (code, docs, speed, memory, release tests)
- less is more

* to do
** errors
*** account name eliding and layout varies between commands and from ledger
*** vty: hledger ui dies showing non-ascii chars in commodity symbol
*** vty: hledger ui shows junk in gnome terminal
** testing
*** test for robust ledger file parsing
**** test all ledger file format features
**** clarify hledgerisms in file format - that hledger can read but ledger can't
**** run ledger 3 baseline tests
*** --compare (xml?) output with ledger's ?
*** build with -Wall and anything else useful
*** build with multiple ghc versions
*** cabal test
*** release tests
**** cabal install with:
***** ghc 6.8
***** ghc 6.10.x
***** windows
***** linux
***** macos
***** no flags
***** happs flag
***** vty flag
** docs/marketing/packaging
*** streamline - less is more
*** automate
**** keep blurbs in sync
***** README file
***** hledger.hs module description
***** hledger.cabal description field (exclude home page link)
***** home page description (http://joyful.com/Hledger/editform)
***** mail list description (http://groups.google.com/groups/hledger -> edit welcome msg)
***** gmane description
***** darcsweb description
**** keep Options.hs and README option list in sync
**** discover commands for --help
**** accouncements
*** document smart dates, period expressions, display expressions
*** develop funding process
**** license change ?
**** donate button, see chimoo guy
**** funding document 2009/01
=======
funding
=======

vision
======

     How to grow the hledger project ?

     I'm looking for ways to fund active and sustainable hledger
     development by me and others.

     A secondary goal is to develop new sustainable models and processes
     for funding free software developers and other community projects.

     This is sometimes the point in a free sw project's development where
     the project leader seemingly loses the plot, alienates contributors
     and destroys the community's good-will dynamic.  I've seen it many
     times, but a few have succeeded and I want to be one of them - so
     that I can eat, have a modicum of stability and do my best work in
     service to the community.  At worst, I'll look bad but the project
     will still be out there. At best I'll live more easily and joyfully
     while serving the cause of Financial Solvency!

     So I'm beginning by posting these notes and inviting your thoughts -
     as much or as little as folks want to give. How could we do this 
     so that all benefit ?
     
funding models
==============
     Brainstorming some possible funding models & processes.

     * grants

      How to find possible grant sources ?

      * con

       * getting grant funding is a whole new field to study
       * slow and time intensive, I imagine

     * donations

      Solicit donations.

      * pro

       * simple

      * con

       * often difficult
       * donators do not feel a direct benefit

     * shareware

      Release the project under a non-free license, requiring commercial
      users to pay the fee on an honour basis (eg).

      * pro

       * flexible, low administration, encourages trust

      * con

       * effectively closed-source ? would inhibit collaboration
       * benefit is still indirect, only a proportion will pay
       * enforcement/guilt may come into play

     * limited-time premium branch

      The funded version of hledger gets some desirable premium features
      before the free version and is closed-source.  Funders/customers pay
      a fixed price for immediate access to the funded version.  Yearly, a
      new funded version is released and the old funded version is merged
      into the free version.  (To gain experience it could be done on a
      smaller scale, eg monthly/quarterly.)

      * pro

       * all features reach community, predictably
       * customers are also community funders
       * customers receive direct benefit from paying

      * con

       * free sw developers compete/outshine the premium branch

     * bounties

      Some (or all) feature, bugfix, project management or other tasks are
      published with a bounty attached.  When the bounty is paid by one or
      more funders, the task is performed and delivered. Or, bounty is paid
      on completion of task (honour system).

      * pro

       * funders receive direct benefit

     * bounties using fundable.org (eg)

      A more organised form of the above, perhaps facilitating trust,
      co-funding and larger bounties.

      * pro

       * proven process developed by others

      * con

       * fundable takes a cut

     * hosted service

      Offer hosted and managed ledgers, perhaps with premium features, for
      a monthly fee

      * pro

       * proven model
       * clear benefit to customers, especially non-technies

      * con
 
       * success of free/self-installed version competes with hosting service
       * some will avoid web-hosting their financial data

     * customisation

      Offer per-user customisations, possibly to be merged in the trunk,
      for a fee

     * support

      Offer user/developer support for a fee

     * training

      Offer application and/or financial training for a fee

     * profit sharing/tithing

      Each period (quarter, half-year, year), donate 10% (eg) to project
      contributors and/or supporting projects

     * transparent funding

      Funding and usage of funds is published on the web as a ledger

     * opaque funding

      All funding and spending need not be made public

strengths
=========
     hledger has some aptitudes in this area:

    * hledger deals with money => hledger users will tend to have some money
    * hledger's purpose is to increase financial success => users will feel its value to their bottom line
    * hledger is a tool that can support project funding, eg by publishing community funding data

weaknesses
==========
    * hledger doesn't have a nice ui yet
    * hledger has a limited featureset
    * hledger requires work, eg data entry and chart of accounts maintenance
    * hledger is geeky
    * there is competition
    * hledger has no compelling market niche (aside from payment-averse free software users)

competitors/fellow niche inhabitants
====================================

    * web apps

     * netsuite
     * sql-ledger, ledgersmb
     * wesabe
     * ...

    * desktop apps

     * quickbooks
     * quicken
     * ms money
     * grisbi
     * gnucash
     * excel
     * ledger!
     * ...

***** responses
***** albino
      have you considered talking to business who hate their financial sw and going from there
***** gwern
      most haskellers have never heard of hledger, sounds arrogant or hubristic to talk of charging for it

**** qooxledger
*** better screenshots
*** screencasts
*** developer docs
**** style guide
***** see above
**** unsafe things which may fail at runtime
***** incomplete pattern matching
***** error
***** printf
*** cabal haddock
*** liveness
**** show feeds on site ?
***** commits (darcsweb)
**** weekly repo activity summary on list
**** available feeds
*** make installation easier
**** on all platforms
***** set up binary publishing
***** reduce dependencies
***** split packages ?
**** on linux
***** debian
***** ubuntu
**** on mac
***** ports
***** binary
**** on windows
***** binary
**** cabal packages after installing ghc 6.10.3, HP, hledger 0.5.1
/usr/local/lib/ghc-6.10.3/./package.conf:
    Cabal-1.6.0.3, GLUT-2.1.1.2, HTTP-4000.0.6, HUnit-1.2.0.3,
    OpenGL-2.2.1.1, QuickCheck-1.2.0.0, array-0.2.0.0, base-3.0.3.1,
    base-4.1.0.0, bytestring-0.9.1.4, cgi-3001.1.7.1,
    containers-0.2.0.1, directory-1.0.0.3, (dph-base-0.3),
    (dph-par-0.3), (dph-prim-interface-0.3), (dph-prim-par-0.3),
    (dph-prim-seq-0.3), (dph-seq-0.3), editline-0.2.1.0,
    extensible-exceptions-0.1.1.0, fgl-5.4.2.2, filepath-1.1.0.2,
    (ghc-6.10.3), ghc-prim-0.1.0.0, haddock-2.4.2,
    haskell-platform-2009.2.0.1, haskell-src-1.0.1.3,
    haskell98-1.0.1.0, hpc-0.5.0.3, html-1.0.1.2, integer-0.1.0.1,
    mtl-1.1.0.2, network-2.2.1, network-2.2.1.1, old-locale-1.0.0.1,
    old-time-1.0.0.2, packedstring-0.1.0.1, parallel-1.1.0.1,
    parsec-2.1.0.1, pretty-1.0.1.0, process-1.0.1.1, random-1.0.0.1,
    regex-base-0.72.0.2, regex-compat-0.71.0.1, regex-posix-0.72.0.3,
    rts-1.0, stm-2.1.1.2, syb-0.1.0.1, template-haskell-2.3.0.1,
    time-1.1.2.4, time-1.1.3, unix-2.3.2.0, xhtml-3000.2.0.1,
    zlib-0.5.0.0
/home/simon/.ghc/i386-linux-6.10.3/package.conf:
    csv-0.1.1, hledger-0.5.1, mtlparse-0.0.1, regex-base-0.93.1,
    regex-compat-0.71.0.1, regex-pcre-0.94.1, regex-posix-0.72.0.3,
    regexpr-0.5.1, split-0.1.1, testpack-1.0.2, utf8-string-0.3.4
**** packages after hledger -fhapps -fvty

*** issues with pandoc's rst support
**** treats HOME's h2s as h1
**** quotes only first line of a :: literal block
**** doesn't support http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#indirect-hyperlink-targets
** code cleanup
*** resources
http://community.haskell.org/~ndm/downloads/paper-hoogle_overview-19_nov_2008.pdf -> Design Guidelines
*** seek more modularity
*** try export lists
*** graph and reduce dependencies
*** pair programming
*** levels of abstraction
**** balance sheet view - data model, view layout
**** hledger web framework - define routes, handlers/views/actions/controllers/presenters, skins/styles..
**** happstack - ? happstack api..
**** hledger app platform - hledger.hs, Options, Utils, withLedgerDo..
**** hledger lib - Ledger, TimeLog, Account, Transaction, Commodity..
**** hledger dev platform - make build, ci, test, bench, prof, check, release..
**** general libs - directory, parsec, regex-*, HUnit, time..
**** cabal - hledger.cabal, hackage..
**** ghc - ghc 6.8, 6.10..
**** haskell 98
**** unix/windows/mac platform
** features/wishlist
*** actual & effective txn & posting dates
*** allow no command or unordered command with pattern args
*** --flat timelog balance report option for clients
*** alternative easy timelog format
*** better web gui
*** nice reports with charts
*** data entry!
*** watching a changing ledger
*** wide format
*** more date syntax ? last nov, next friday, optional this, week of
*** more period syntax ? every N days, biweekly
*** allow comment lines immediately after or within an entry
*** accept multiple -f files
*** more reliable tidy layout from print
*** parse more file formats - gnucash, qif, ofx, csv..
*** i18n
*** speed
**** optimisation
**** speed regression tests
*** plugins
* misc
** things I want to know
*** time
where have I been spending my time in recent weeks ?
where have I spent my time today ?
what is my status wrt spending plan for this week/month/year ?
what is my current status wrt time spending goals ?
*** money
where have I been spending my money ?
what is my status wrt spending plan for this week/month/year ?
what is my current status wrt spending/savings goals ?
what are all my current balances ?
what does my balance history look like ?
what does my balance future look like ?
are there any cashflow, tax, budgetary problems looming ?
*** charts
[1:27pm] <sm> I have decided I am not getting enough visible day-to-day value out of my ledger, I need more of that to stay motivated
[1:27pm] <Nafai> What do you think will help in that?
[1:27pm] <sm> I think some simple self-updating charts, or even good reports in a visible place
[1:28pm] <sm> something I don't have to spend an hour fiddling with to get answers
[1:38pm] <sm> Nafai: identifying/designing some useful reports/charts seems to be blocking me
[1:39pm] <sm> there are probably some standard ones I should use
[1:40pm] <sm> a graph of daily net worth is probably one of the simplest
[1:58pm] <sm> what else.. a chart of weekly expenses in key categories
[1:58pm] <sm> ditto, monthly
[1:58pm] <sm> a chart of monthly income
[1:59pm] <sm> those three should help me be more clear about cashflow status
[2:00pm] <sm> also I'd like something that shows me how much I am on top of financial tracking - how current my numbers are, when last reconciled etc - at a glance
[2:01pm] <sm> another simple one: current balances in all accounts
[2:01pm] <sm> those would be a great start
[2:04pm] <sm> daily net worth, weekly expense, monthly expense, monthly income, confidence/currentness report, and balance report
[2:05pm] <sm> let's see, which of those 6 would give most payoff right now
[2:05pm] <sm> probably 5
[2:06pm] <sm> how could I measure that ?
[2:06pm] <sm> number of days since last ledger entry..
[2:06pm] <sm> number of ledger entries in last 30 days (compared to average)
[2:07pm] <sm> number of days since last cleared checking entry (indicating an online reconcile)
[2:08pm] <sm> those would be a good start. How do I make those visual
[2:09pm] <sm> well I guess the first step is a script to print them

** data representation
*** http://www.python.org/dev/peps/pep-0327/
*** http://www.n-heptane.com/nhlab/repos/Decimal/
*** http://www.n-heptane.com/nhlab/repos/Decimal/Money.hs
*** http://www2.hursley.ibm.com/decimal/
** snippets
-- trace a MixedAmount
matrace :: MixedAmount -> MixedAmount
matrace a@(Mixed as) = trace (show as) a

-- normalise and trace a MixedAmount
nmatrace :: MixedAmount -> MixedAmount
nmatrace a = trace (show as) a where (Mixed as) = normaliseMixedAmount a

** http://lwn.net/Articles/314577/
** financial software
*** http://weberp.org
**** http://www.weberp.org/weberp/doc/Manual/ManualContents.php