hledger/DEVELOPMENT.md

290 lines
11 KiB
Markdown
Raw Normal View History

2010-11-19 23:14:27 +03:00
---
2012-03-25 01:28:50 +04:00
title: hledger contributor guide
2010-11-19 23:14:27 +03:00
---
2012-03-25 01:28:50 +04:00
# Contributor guide
2010-11-19 23:14:27 +03:00
2010-12-12 20:51:14 +03:00
## Quick links
2010-11-19 23:14:27 +03:00
2011-06-24 07:38:00 +04:00
**Support**<br>
2012-03-12 00:06:50 +04:00
IRC channel: [irc.freenode.net/#ledger](irc://irc.freenode.net/#ledger)
2011-06-24 07:38:00 +04:00
<br>Mail list: [list.hledger.org](http://list.hledger.org)
<br>Bug tracker: [bugs.hledger.org](http://bugs.hledger.org)
2012-03-12 00:06:50 +04:00
<br>Tips: [how to get help](#how-to-get-help)
2011-06-24 07:38:00 +04:00
**Released version**<br>
2012-03-12 00:06:50 +04:00
[release notes](NEWS.html),
[hledger-web demo](http://demo.hledger.org)
<br>
[ready-to-run binaries](DOWNLOADS.html)
<br>
2010-12-12 20:51:14 +03:00
[hledger](http://hackage.haskell.org/package/hledger),
2011-06-24 07:38:00 +04:00
[hledger-web](http://hackage.haskell.org/package/hledger-web),
2010-12-07 12:59:33 +03:00
[hledger-vty](http://hackage.haskell.org/package/hledger-vty),
2012-03-12 00:06:50 +04:00
[hledger-chart](http://hackage.haskell.org/package/hledger-chart),
[hledger-lib](http://hackage.haskell.org/package/hledger-lib)
packages
2011-06-24 07:38:00 +04:00
**Development version**<br>
2011-07-15 04:27:48 +04:00
[Get it](#how-to-set-up-for-hledger-development),
2012-03-12 00:06:50 +04:00
[browse it](http://joyful.com/repos/hledger)
<!-- [hledger-web dev demo](http://demo.hledger.org:5001) -->
<br>
2012-02-23 18:47:10 +04:00
[developer notes](http://joyful.com/darcsweb/darcsweb.cgi?r=hledger;a=plainblob;f=/NOTES.org),
2011-04-23 18:53:07 +04:00
[haddock coverage](http://hledger.org/profs/haddock-coverage),
2012-03-12 00:06:50 +04:00
[unit test coverage](http://hledger.org/profs/coverage/hpc_index_fun.html),
2012-03-11 22:50:29 +04:00
<!-- [benchmark](http://hledger.org/profs/latest.bench), -->
<!-- [profile](http://hledger.org/profs/latest.prof), -->
<!-- [heap](http://hledger.org/profs/latest.ps) -->
2012-03-12 00:06:50 +04:00
[stale dependencies](http://packdeps.haskellers.com/feed/?needle=hledger)
reports
<br>
<script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/jquery-1.4.2.js"></script>
<script type="text/javascript" src="http://haskell.org/hoogle/datadir/resources/hoogle.js"></script>
<form action="http://haskell.org/hoogle/" method="get" style="display:inline; margin:0; padding:0;">
[browse dev API docs](http://hledger.org/api/frames.html)
or
<input type="hidden" name="prefix" value="+hledger +hledger-lib +hledger-web +hledger-vty +hledger-chart" />
<span style="white-space:nowrap;"
><input type="text" name="hoogle" id="hoogle" accesskey="1" size="30"
/><input type="submit" value="search released API docs"
/></span>
2011-01-23 18:20:20 +03:00
</form>
2012-03-12 00:06:50 +04:00
2010-12-12 20:51:14 +03:00
## How to..
### how to get help
2012-03-12 00:06:50 +04:00
- join and use the [hledger mail list](http://list.hledger.org)
2010-12-12 20:51:14 +03:00
- chat Simon (sm) on the
[\#ledger](irc://irc.freenode.net/#ledger) irc channel which we
share, or [send email](mailto:simon@joyful.com?subject=hledger:)
2011-06-24 07:38:00 +04:00
- for issues relevant to the wider *ledger community, you can also use or cc [ledger's mail list](http://list.ledger-cli.org)
- don't forget the [installation tips](MANUAL.html#installing), [Troubleshooting](MANUAL.html#troubleshooting) section, and [bug tracker](http://bugs.hledger.org)
2010-12-12 20:51:14 +03:00
### how to report problems
2012-03-12 00:06:50 +04:00
- check for related issues at [bugs.hledger.org](http://bugs.hledger.org) ([view all](http://bugs.hledger.org/grid)) or in the [list archive](https://groups.google.com/d/forum/hledger)
2010-12-12 20:51:14 +03:00
- discuss/confirm the issue on irc or list
- [report](http://code.google.com/p/hledger/issues/entry) new issues in the bug tracker
<!-- - test and share problem journal snippets at paste . hledger.org -->
### 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](#how-to-run-the-tests)
- discuss/report problems via irc/mail list/bug tracker
### how to help with bug tracking
2012-03-12 00:06:50 +04:00
- get to know the [bug tracker](http://bugs.hledger.org) and its contents
- join the [hledger google project](http://code.google.com/p/hledger/) to get more access
2010-12-12 20:51:14 +03:00
- research and update issues
2012-03-12 00:06:50 +04:00
- use these convenience urls:
[`bugs.hledger.org`](http://bugs.hledger.org)
[`bugs.hledger.org/grid`](http://bugs.hledger.org/grid)
[`bugs.hledger.org/new`](http://bugs.hledger.org/new)
`bugs.hledger.org/NNN`
2010-12-12 20:51:14 +03:00
### how to set up for hledger development
2011-08-20 19:48:27 +04:00
1. get an up-to-date [ghc](http://haskell.org/ghc), at least 6.12.3 but preferably 7
2. there's probably no need to install the [haskell platform](http://haskell.org/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](http://darcs.net), at least 2.x and preferably newer: use a binary package or `cabal install darcs`
2010-12-12 20:51:14 +03:00
- get the hledger repo:
darcs get --lazy http://joyful.com/darcsden/simon/hledger
2010-12-12 20:51:14 +03:00
cd hledger
- install packages required to build hledger and add-ons, or as many of them as possible:
cabal update
make install
2011-08-20 23:18:24 +04:00
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.
2011-08-20 19:48:27 +04:00
- 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.
2010-12-12 20:51:14 +03:00
- 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](#how-to-set-up-for-hledger-development)
- you should receive a reply shortly. If in doubt, [follow up](#how-to-get-help) 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
- after getting one or more patches committed, read and sign the [contributor list & agreement](CONTRIBUTORS.html)
- or, [ask](#how-to-get-help) to be added
### how to do code review
- watch for and read new patches on the mail list, irc, darcsweb patch feed, or [darcsweb patch log](http://joyful.com/darcsweb/darcsweb.cgi?r=hledger;a=shortlog)
- set up for development and test new patches in your own repo
- read the existing [code docs and source](#quick-links)
- 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 overview
2010-12-12 20:51:14 +03:00
A rough overview/blueprint for the hledger project.
2010-12-12 20:51:14 +03:00
### 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
- the main repo is served from a private darcsden instance on joyful.com
- darcsweb is also available as an alternate browsing UI
2010-12-12 20:51:14 +03:00
<!-- <a href="http://joyful.com/darcsweb/darcsweb.cgi?r=hledger"><img src=http://joyful.com/repos/hledger/commits.png border=0></a> -->
2010-12-12 20:51:14 +03:00
<!-- ### release process -->
<!-- ### roadmap -->
<!-- ### communication and collaboration -->
<!-- ### web presence and hosting setup -->
<!-- ### finances and other resources -->
<!-- ### licensing and legal issues -->
<!-- ### contributors and credits -->
2010-11-19 23:14:27 +03:00
2010-12-12 20:51:14 +03:00
## Related projects
2010-11-19 23:14:27 +03:00
- I have a few older bits and pieces [here](http://joyful.com/Ledger)
2010-12-12 20:51:14 +03:00
- John Wiegley's [ledger](http://wiki.github.com/jwiegley/ledger) inspired hledger.
- Tim Docker's [ledger-reports](http://dockerz.net/repos/ledger-reports) builds on hledger to generate
[html reports](http://dockerz.net/software/hledger_report_sample/report.html)
- [beancount](https://furius.ca/beancount/) is another ledger clone, in python
- h/ledger inspired Uwe Hollerbach's [umm](http://www.korgwal.com/umm/)
2011-05-16 19:50:23 +04:00
- [http://darcsden.com/alex/bill](http://darcsden.com/alex/bill), [http://darcsden.com/alex/bill-atomo](http://darcsden.com/alex/bill-atomo), [http://darcsden.com/alex/bill-scheme](http://darcsden.com/alex/bill-scheme) - a time-tracking and billing app
- [http://darcsden.com/ozamosi/debts](http://darcsden.com/ozamosi/debts) - Silly debt tracking webapp
- [http://darcsden.com/housetab-multi](http://darcsden.com/dbp/housetab-multi), [housetab.org](http://housetab.org) - a webapp to manage expenses between a group of friends.
2010-11-19 23:14:27 +03:00
2010-12-12 20:51:14 +03:00
<!-- <a href="https://www.google.com/analytics/reporting/?reset=1&id=15489822" accesskey="a"></a> -->