simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-11-10 14:16:41 +03:00
Code Issues Projects Releases Wiki Activity
bea6fb7464
hledger/DEVELOPMENT.md
Simon Michael 0e8433fbce site: fix dev -> api link
2011-09-02 01:02:05 +00:00

10 KiB
Raw Blame History

title
hledger developers' guide

Developers' guide

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

Quick links

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

  • install darcs if you don't have it (version 2)

  • 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 the development version of the hledger packages, so ghc-pkg unregister those afterwards if you don't want that.

  • 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

Related projects