hledger/DEVELOPMENT.md
2011-05-16 15:50:23 +00:00

11 KiB

title
hledger developers' guide

Developers' guide

Quick links for everyone, plus a rough guide mostly for hledger contributors and developers.

Support
Users and developers:
how to get help
IRC channel: irc.freenode.net/#ledger
Mail list: list.hledger.org
Bug tracker: bugs.hledger.org

Released version
Binaries, release notes, hledger-web demo
Hackage: hledger, hledger-web, hledger-vty, hledger-chart, hledger-lib

**Latest development version**
[Get it](#how-to-set-up-for-hledger-development), [browse it](http://joyful.com/darcsweb/darcsweb.cgi?r=hledger), [hledger-web dev demo](http://demo.hledger.org:5001)
[API haddocks](http://hledger.org/api)
[Developer notes](http://joyful.com/darcsweb/darcsweb.cgi?r=hledger;a=plainblob;f=/NOTES), [haddock coverage](http://hledger.org/profs/haddock-coverage), [unit test coverage](http://hledger.org/profs/coverage/hpc_index_fun.html), [benchmark](http://hledger.org/profs/latest.bench), [profile](http://hledger.org/profs/latest.prof), [heap](http://hledger.org/profs/latest.ps) reports

How to..

how to get help

how to report problems

how to help with testing

  • review and test our documentation and web presence
  • download and test the binaries on your platform
  • test installing via cabal
  • use the tools and test functionality, usability, browser compatibility, ui layout etc.
  • check that hledger test reports no failures
  • run the developer tests
  • discuss/report problems via irc/mail list/bug tracker

how to help with bug tracking

  • get to know the bug tracker and its contents
  • join its google project for more access
  • research and update issues

how to set up for hledger development

  1. get an up-to-date ghc, at least 6.12.3 but preferably 7
  2. there's probably no need to install the haskell platform now, but you could
  3. it's probably worth getting the latest and best cabal: cabal update; cabal install cabal-install
  4. get an up-to-date darcs, at least 2.x and preferably newer: use a binary package or cabal install darcs
  • get the hledger repo:

      darcs get --lazy http://joyful.com/repos/hledger
      cd hledger
    
  • install packages required to build hledger and add-ons, or as many of them as possible:

      cabal update
      make install
    

    This will also try to cabal install development builds of the hledger executables, so ghc-pkg unregister those afterwards if you don't want that.

  • try building with make:

      make bin/hledger
    

    This is usually quicker and simpler than fiddling with multiple cabal packages during development.

  • try auto-building with sp:

      darcs get http://joyful.com/repos/searchpath
      searchpath$ make, add sp to your path
      hledger$ make autotest
    

    This is how I do most hledger development. It will recompile whenever you save changes to source files. You'll need to install sp as shown.

  • test patch sending. Make a dummy change:

      echo >>README.markdown; darcs record README.markdown -a -m 'my test patch'
    

    send it to yourself:

      darcs send --to me@my.address
    

    and make sure you receive it. If not, your system may not be configured to send email from the command line. Try to fix that. As a last resort, you can darcs send -O and mail the resulting patch file to the list. Finally, clean up:

      darcs obliterate -p 'my test patch'
    

how to get your patch committed

  • send it
  • you should receive a reply shortly. If in doubt, follow up at any time.
  • respond to any code review feedback, submitting new patches if needed, until you receive a "patch applied" acknowledgement
  • to verify the patch is in the main repo: listen for it on irc or look for it in darcsweb

how to improve the documentation

  • get familiar with the website and documentation online, review and test
  • get familiar with the site/doc source files (see Makefile)
  • set up for hledger development
  • send patches with names prefixed with "doc: " (or "site: ")

how to run the tests

  • set up for hledger development
  • cabal install shelltestrunner
  • make test

how to add a test

  • identify what to test
  • choose the test type: unit ? functional ? benchmark ?
  • currently expected to pass or fail ?
  • figure out where it goes
  • write test, verify expected result
  • get it committed

how to fix a bug or add a feature

  • research, discuss, validate the issue/feature on irc/list/bug tracker
  • look for related tests, run the tests and check they are passing
  • add a test ?
  • develop a patch
  • include any related issue numbers in the patch name, eg: "fix for blah blah (#NNN)"
  • get it committed

how to become a contributor

how to do code review

  • watch for and read new patches on the mail list, irc, darcsweb patch feed, or darcsweb patch log
  • set up for development and test new patches in your own repo
  • read the existing code docs and source
  • send feedback or discuss via irc or list

how to help with packaging

  • package hledger for linux distros, macports, etc.
  • develop mac/windows installers
  • find and assist distro packagers/installer developers

how to help with project management

  • clarify/update goals and principles
  • monitor, report on project progress and performance
  • research, compare and report on successful projects, related projects
  • identify collaboration opportunities
  • marketing, communication, outreach
  • release management, roadmap planning

Project notes

This will grow into an overall description/blueprint for the hledger project.

mission, principles, goals

The hledger project aims to produce:

  • a practical, accessible, dependable tool for end users
  • a useful library and toolbox for finance-minded haskell programmers
  • a successful, time-and-money-solvent project within a thriving ecosystem of financial software projects.

roles and activities

  • newcomer/potential user
  • user
  • library user
  • field tester
  • bug wrangler
  • support
  • documentor
  • qa
  • developer
  • packager
  • communicator
  • project manager

documentation

  • website
  • user manual
  • developer guide
  • code documentation: haddock
  • various developer reports
  • developer notes outline
  • blurbs: in cabal files, module headers, google project, repo message of the day..

quality assurance

  • unit tests (HUnit, make unittest)
  • functional tests (shelltestrunner, make functest)
  • performance tests (simplebench, make bench)
  • documentation tests (make haddocktest + manual)
  • ui tests (manual)
  • installation tests (manual)

code