Merge pull request #1 from gratipay/2012-06

reconcile 2012-06

.travis.yml

@@ -0,0 +1,13 @@
+os: osx
+branches:
+  only:
+    - master
+before_install:
+  - python2.7 --version
+  - brew update
+  - brew install ledger
+  - ledger --version
+install: ""
+script: ./bin/test.py
+notifications:
+  email: false

2012/06.dat

@@ -0,0 +1,210 @@
+2012-06-01  Opening Balance
+    Assets:Operations:New Alliance                                  $   102.45
+    Equity:Owners:Chad Whitacre
+
+; Gittip Payday 0
+2012-06-01  Users
+    Assets:Escrow:Samurai                                           $     2.96
+    Assets:Fee Buffer:Samurai                                       $     0.34
+    Income:Fee Buffer:Samurai                                      -$     0.34
+    Income:Escrow:Samurai
+2012-06-01  Retained Earnings
+    Income:Escrow:Samurai                                           $     2.96
+    Income:Fee Buffer:Samurai                                       $     0.34
+    Equity:Retained Earnings                                       -$     0.34
+    Liabilities:Escrow
+
+2012-06-04  Settlement
+    ; We expected $3.30, but saw $7.56 instead: an overpayment of $4.26.
+    Assets:Escrow:New Alliance                                      $     2.96
+    Assets:Fee Buffer:New Alliance                                  $     0.34
+    Assets:Operations:New Alliance                                  $     4.26
+    Income:Operations:Errors:Samurai                               -$     4.26
+    Assets:Fee Buffer:Samurai                                      -$     0.34
+    Assets:Escrow:Samurai
+2012-06-04  Retained Earnings
+    Income:Operations:Errors:Samurai                                $     4.26
+    Equity:Retained Earnings
+
+2012-06-04  Samurai
+    Expenses:Fee Buffer:Samurai                                     $     0.08
+    Assets:Fee Buffer:New Alliance
+2012-06-04  Retained Earnings
+    Equity:Retained Earnings                                        $     0.08
+    Expenses:Fee Buffer:Samurai
+
+2012-06-04  Samurai
+    Expenses:Fee Buffer:Samurai                                     $    31.35
+    Assets:Fee Buffer:New Alliance
+2012-06-04  Retained Earnings
+    Equity:Retained Earnings                                        $    31.35
+    Expenses:Fee Buffer:Samurai
+
+; Gittip Payday 1
+2012-06-08  Users
+    Assets:Escrow:Samurai                                           $    23.17
+    Assets:Fee Buffer:Samurai                                       $     2.11
+    Income:Fee Buffer:Samurai                                      -$     2.11
+    Income:Escrow:Samurai
+2012-06-08  Retained Earnings
+    Income:Escrow:Samurai                                           $    23.17
+    Income:Fee Buffer:Samurai                                       $     2.11
+    Equity:Retained Earnings                                       -$     2.11
+    Liabilities:Escrow
+
+2012-06-11  Settlement
+    ; AMEX
+    ; We expected 0.61, and we saw 0.61.
+    Assets:Escrow:New Alliance                                      $     0.48
+    Assets:Fee Buffer:New Alliance                                  $     0.13
+    Assets:Fee Buffer:Samurai                                      -$     0.13
+    Assets:Escrow:Samurai
+
+2012-06-11  Settlement
+    ; VISA + MasterCard
+    ; We expected $24.67, but only saw $24.11: an underpayment of $0.56.
+    Assets:Escrow:New Alliance                                      $    22.69
+    Assets:Fee Buffer:New Alliance                                  $     1.98
+    Expenses:Operations:Errors:Samurai                              $     0.56
+    Assets:Operations:New Alliance                                 -$     0.56
+    Assets:Fee Buffer:Samurai                                      -$     1.98
+    Assets:Escrow:Samurai
+2012-06-11  Retained Earnings
+    Equity:Retained Earnings                                        $     0.56
+    Expenses:Operations:Errors:Samurai
+
+2012-06-11  Samurai
+    Expenses:Fee Buffer:Samurai                                     $     2.00
+    Assets:Fee Buffer:New Alliance
+2012-06-11  Retained Earnings
+    Equity:Retained Earnings                                        $     2.00
+    Expenses:Fee Buffer:Samurai
+
+; Gittip Payday 2
+2012-06-15  Users
+    Assets:Escrow:Samurai                                           $     1.36
+    Assets:Fee Buffer:Samurai                                       $     0.69
+    Income:Fee Buffer:Samurai                                      -$     0.69
+    Income:Escrow:Samurai
+2012-06-15  Retained Earnings
+    Income:Escrow:Samurai                                           $     1.36
+    Income:Fee Buffer:Samurai                                       $     0.69
+    Equity:Retained Earnings                                       -$     0.69
+    Liabilities:Escrow
+
+; Our first payout! Chad took money out of his pocket and put it in Steve Klabnik's hand.
+2012-06-15  Owners
+    ; Chad increases our escrow with cash from his pocket, pushing above what we need.
+    Assets:Escrow:Cash                                              $     1.50
+    Equity:Owners:Chad Whitacre
+2012-06-15  Escrow
+    ; We bleed off the excess escrow over to operations(!?).
+    Assets:Operations:New Alliance                                  $     1.50
+    Assets:Escrow:New Alliance
+2012-06-15  Users
+    ; Now we can do the payout ...
+    Expenses:Escrow:Cash                                            $     1.50
+    Income:Fee Buffer:Cash                                          $     0.00
+    Assets:Fee Buffer:Cash                                         -$     0.00
+    Assets:Escrow:Cash
+2012-06-15  Retained Earnings
+    Liabilities:Escrow                                              $     1.50
+    Equity:Retained Earnings                                        $     0.00
+    Expenses:Fee Buffer:Cash                                       -$     0.00
+    Expenses:Escrow:Cash
+
+2012-06-18  Settlement
+    ; We expected $2.05, but only saw $2.01: an underpayment of $0.04.
+    Assets:Escrow:New Alliance                                      $     1.36
+    Assets:Fee Buffer:New Alliance                                  $     0.69
+    Expenses:Operations:Errors:Samurai                              $     0.04
+    Assets:Operations:New Alliance                                 -$     0.04
+    Assets:Fee Buffer:Samurai                                      -$     0.69
+    Assets:Escrow:Samurai
+2012-06-18  Retained Earnings
+    Equity:Retained Earnings                                        $     0.04
+    Expenses:Operations:Errors:Samurai
+
+; Testing out Stripe
+2012-06-15  Users
+    Assets:Operations:Stripe                                        $     0.54
+    Income:Operations:Verification & Testing
+2012-06-15  Retained Earnings
+    Income:Operations:Verification & Testing                        $     0.54
+    Equity:Retained Earnings
+
+2012-06-22  Stripe
+    Expenses:Operations:Processing:Stripe                           $     0.32
+    Assets:Operations:Stripe
+2012-06-22  Retained Earnings
+    Equity:Retained Earnings                                        $     0.32
+    Expenses:Operations:Processing:Stripe
+
+2012-06-22  Settlement
+    Assets:Operations:New Alliance                                  $     0.22
+    Assets:Operations:Stripe
+
+; Gittip Payday 3
+2012-06-22  Users
+    Assets:Escrow:Stripe                                            $    20.67
+    Assets:Fee Buffer:Stripe                                        $     4.62
+    Income:Fee Buffer:Stripe                                       -$     4.62
+    Income:Escrow:Stripe
+2012-06-22  Retained Earnings
+    Income:Escrow:Stripe                                            $    20.67
+    Income:Fee Buffer:Stripe                                        $     4.62
+    Equity:Retained Earnings                                       -$     4.62
+    Liabilities:Escrow
+
+2012-06-22  Stripe
+    Expenses:Fee Buffer:Stripe                                      $     4.32
+    Assets:Fee Buffer:Stripe
+2012-06-22  Retained Earnings
+    Equity:Retained Earnings                                        $     4.32
+    Expenses:Fee Buffer:Stripe
+
+2012-06-28  Settlement
+    Assets:Escrow:New Alliance                                      $    20.67
+    Assets:Fee Buffer:New Alliance                                  $     0.30
+    Assets:Fee Buffer:Stripe                                       -$     0.30
+    Assets:Escrow:Stripe
+2012-06-28  Settlement
+
+; Gittip Payday 4
+2012-06-29  Users
+    Assets:Escrow:Stripe                                            $    95.24
+    Assets:Fee Buffer:Stripe                                        $    15.76
+    Income:Fee Buffer:Stripe                                       -$    15.76
+    Income:Escrow:Stripe
+2012-06-29  Retained Earnings
+    Income:Escrow:Stripe                                            $    95.24
+    Income:Fee Buffer:Stripe                                        $    15.76
+    Equity:Retained Earnings                                       -$    15.76
+    Liabilities:Escrow
+
+2012-06-29  Stripe
+    Expenses:Fee Buffer:Stripe                                      $    14.63
+    Assets:Fee Buffer:Stripe
+2012-06-29  Retained Earnings
+    Equity:Retained Earnings                                        $    14.63
+    Expenses:Fee Buffer:Stripe
+
+; IHasAMoney.com
+2012-06-18  Users
+    Assets:Operations:Samurai                                       $     2.92
+    Income:Operations:IHasAMoney.com
+2012-06-18  Retained Earnings
+    Income:Operations:IHasAMoney.com                                $     2.92
+    Equity:Retained Earnings
+2012-06-18  Settlement
+    Assets:Operations:New Alliance                                  $     2.92
+    Assets:Operations:Samurai
+2012-06-25  Users
+    Assets:Operations:Samurai                                       $     2.99
+    Income:Operations:IHasAMoney.com
+2012-06-25  Retained Earnings
+    Income:Operations:IHasAMoney.com                                $     2.99
+    Equity:Retained Earnings
+2012-06-25  Settlement
+    Assets:Operations:New Alliance                                  $     2.99
+    Assets:Operations:Samurai

README.md

@@ -1,3 +1,95 @@
-This is Gratipay's financial accounting system, which is based on [Ledger
-3](http://ledger-cli.org/). We have a directory for each year, and a `NN.dat`
-file for each month. Scripts are in the `bin/` directory.
+# Gratipay Finances
+
+This is [Gratipay](https://gratipay.com/)'s financial accounting system, which
+is based on [Ledger](http://ledger-cli.org/). We have a directory for each
+year, and an `NN.dat` file for each month. Our wrapper scripts are in the
+`bin/` directory; add it to your `PATH` for best results. Each month gets [a
+PR](https://github.com/gratipay/finances/pulls).
+
+[![status](https://api.travis-ci.org/gratipay/finances.svg)](https://travis-ci.org/gratipay/finances)
+
+
+## How Our Books are Organized
+
+The biggest reality in our finances is that we have **operations**—*our*
+money—and then we have **escrow**—*other people's* money. Never the
+twain shall meet (more or less). Beyond the basic accounting principle that
+assets must equal liabilities plus equity, nearly as important for Gratipay is
+that escrow assets must always equal escrow liability: when people think we're
+holding their money, we better be holding their money!
+
+Actually, though, our income from processing fees comes to us from our upstream
+processors commingled with escrow, *and* we want to keep our fee *income* as
+close to our fee *expenses* as possible (our *operating* income, of course,
+comes [through Gratipay](https://gratipay.com/Gratipay/) just like any other
+Gratipay Team).  To deal with this dual reality, we use a **fee buffer**.
+Ideally the balance in the fee buffer is zero, though of course it varies in
+practice.
+
+You'll see, then, that the assets on our balance sheet, as well as our income
+and expenses on our income statement, are broken down according to these three
+second-level categories: escrow, fee buffer, and operations. The fee buffer and
+operations on the income statement hit retained earnings on the balance sheet.
+Escrow on the income statement hits escrow liability on the balance sheet.
+
+Whereas the second-level categories are *logical*, our actual *physical* bank
+and processor accounts end up as third-level categories. So, for example, our
+actual balance at New Alliance Federal Credit Union is equal to the sum of
+these three balance sheet accounts:
+
+ - Assets:Escrow:New Alliance
+ - Assets:Fee Buffer:New Alliance
+ - Assets:Operations:New Alliance
+
+
+## Working on the Finances
+
+First, you'll need [Ledger](http://ledger-cli.org/) (v3),
+[Python](https://www.python.org/) (v2.7), a [text
+editor](https://en.wikipedia.org/wiki/Text_editor), and a [command
+line](https://en.wikipedia.org/wiki/Command-line_interface). Then basically
+what you're gonna do is edit the dat file for the month you're working on, and
+then, from the root of your clone of this repo, run:
+
+```
+clear && test.py && balance-sheet.py && income-statement.py
+```
+
+That'll check for errors (we also have CI set up [at
+Travis](https://travis-ci.org/gratipay/finances)) and then show you a balance
+sheet and income statement.
+
+
+### Style
+
+Here are some style notes for the dat files:
+
+ 1. Group transactions together conceptually.
+
+ 1. Transactions should be generally date-sorted, but it's okay to fudge that a
+    little for the sake of (1).
+
+ 1. Record debits first.
+
+ 1. Symmetry is nice. 
+
+ 1. Use comments! Especially for weird stuff.
+
+
+### Access
+
+Many accounting tasks require access to Gratipay's bank and payment processor
+statements. If you're interested in helping out with such tasks, read [Inside
+Gratipay](http://inside.gratipay.com/) and then introduce yourself on [the
+Radar](http://inside.gratipay.com/howto/sweep-the-radar).
+
+
+# Help
+
+[Open an issue](https://github.com/gratipay/finances/issues/new) if you're having problems.
+
+
+# Legal
+
+The scripts and data in this repo are released into the public domain to the
+extent possible under [CC0](http://creativecommons.org/publicdomain/zero/1.0/).

bin/balance-sheet.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python2.7
+from __future__ import absolute_import, division, print_function, unicode_literals
+
+import sys
+from os import path
+import calendar
+
+ourdir = path.realpath(path.dirname(__file__))
+sys.path.insert(0, ourdir)
+
+import reporting
+
+cmd = [ 'ledger'
+      , 'balance'
+      , '--prepend-width=0' # this is here to satisfy ledger on Travis
+      , '--sort "account =~ /^Assets.*/ ? 0 : '
+      ,        '(account =~ /^Liabilities.*/ ? 1 : '
+      ,        '(account =~ /^Equity.*/ ? 2 : 3))"'
+       ]
+cmd += sys.argv[1:]
+
+year, month = reporting.parse(sys.argv[1:])[1]
+
+# Each year opens with a carryover balance, so we don't have to go further back than that.
+start = [year, None]
+end = [year, month]
+for datfile in reporting.list_datfiles(start, end):
+    cmd.append('-f {}'.format(datfile))
+
+print()
+print("BALANCE SHEET".center(42))
+print("as of {} {}, {}".format( calendar.month_name[int(end[1])]
+                              , calendar.monthrange(int(end[0]), int(end[1]))[1]
+                              , end[0]
+                               ).center(42))
+reporting.report(cmd)