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'd better be holding their money!
Actually, though, our operating income from processing fees comes to us from our upstream processors commingled with escrow, and (as of June, 2013) we want to keep our fee income as close to our fee expenses as possible (our true operating income, of course, comes through Gratipay just like any other project on Gratipay). To deal with this dual reality, we use a fee buffer. Ideally the balance in the fee buffer is zero, but in practice it fluctuates.
You'll see, then, that the assets on our balance sheet are broken down
according to three second-level categories:
Operations. Whereas the second-level asset 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:
Our fiscal year runs from January 1 through December 31.
How This Repo is Organized
There is a directory for each fiscal year, named
FYNNNN (note that fiscal
years are specified by the calendar year in which they end). Inside are two
kinds of files:
NNNN-MM.beancount, containing a single month's worth of transactions; and
FYNNNN.beancount, containing the opening and closing transactions for the year, and including all of the month files.
gratipay.beancount file ties these together, setting
options, and including the transactions from all fiscal years. That's where you
want to point Beancount's scripts.
Working on the Finances
First, you'll need a text editor,
a command line, and
Beancount. Then basically what you're gonna do
is edit the file for the month you're working on, and then, from the root of
your clone of this repo, run
./test.py. That'll check for errors (we also
have CI set up at Travis). To review
the balance sheet and income statement, run
Each month gets a PR entitled
account for YYYY-MM, with a branch named
YYYY-MM. We close the month by
merging the PR. Inside of an open month, we should overwrite transactions as
needed (changes are tracked in Git commits and GitHub comments). Outside of an
open month, we must make any correcting transactions in the current month,
rather than overwriting transactions in an old file.
Each fiscal year also gets a PR entitled
close FYNNNN and/or
(we haven't done this yet so who knows? :). We close the year by merging the
PR(s). Once a year is closed, we mustn't edit it at all, apart from comments.
It's always okay to add or clarify comments.
Here are some style notes for the
*.beancount files, based on a
with our accountant:
- Group transactions together conceptually.
- Transactions should be generally date-sorted, but it's okay to fudge that a little for the sake of (1).
- Record debits first.
- Symmetry is nice.
- Explicate all transaction amounts (don't depend on Beancount's amount interpolation).
- Use comments! Especially for weird stuff.
Many accounting tasks require access to Gratipay's bank and payment processor statements. If you're interested in helping out with such tasks and would like access to our statements, start with Inside Gratipay.
Open an issue if you're having problems.
The scripts and data in this repo are released into the public domain to the extent possible under CC0, and if you don't accept that then you may also use them under the CC or OSI license of your choosing.