doc: 1.12 announcement

[ci skip]

doc/ANNOUNCE

@@ -1,26 +1,169 @@
-hledger is a robust, cross-platform "plain text accounting" tool, for
+hledger is a robust, cross-platform plain text accounting tool, for
 tracking money, time, stocks, cryptocurrencies or any other commodity,
 using double-entry accounting, private or shared plain text files,
 revision control, and command-line, curses or web UIs.
+Find out more at http://hledger.org and http://plaintextaccounting.org.
 
-I'm pleased to announce the on-schedule release of hledger 1.12.
+I'm pleased to announce the release of hledger 1.12!
-Thanks to release contributors: A, B.
+Thank you release contributors Alex Chen, Jesse Rosenthal, Samuel May,
+Mykola Orliuk, Peter Simons, Moritz Kiefer, Dmitry Astapov, Felix Yan,
+Aiken Cairncross, and Nikhil Jha.
 
+After two years of regular quarter-end releases, I am speeding up
+hledger's release cadence: we now aim to release every 1-3 months, as
+needed or wanted, with our normal release window being the first few
+days of each month.
 
-What's new
+Release notes (http://hledger.org/release-notes):
-----------
+-------------------------------------------------
 
 hledger 1.12
 
-- 
+* install script: ensure a new-enough version of stack; more informative output  
 
-- 
+* build with GHC 8.6/base-4.12 (Peter Simons)  
 
-Full release notes are at http://hledger.org/release-notes.html#hledger-1.12
+* add required upper bound for statistics (Samuel May)  
+
+* --anon anonymises more thoroughly (including linked original postings) (Moritz Kiefer)  
+
+* unbalanced transaction errors now include location info (Mykola Orliuk)  
+
+* accounts command: --drop also affects the default flat output, without needing an explicit --flat flag  
+
+* accounts command: the --codes flag has been dropped  
+
+* accounts command: filtering by non-account-name queries now works  
+
+* add command: fix transaction rendering regression during data entry and in journal file  
+
+* balance command: fix wrongful eliding of zero-balance parent accounts in tree mode (Dmitry Astapov)  
+
+* journal format, bs/bse/cf/is commands: account directives can declare account types (#877)  
+  Previously you had to use one of the standard english account names
+  (assets, liabilities..) for top-level accounts, if you wanted them to
+  appear in the right place in the balancesheet, balancesheetequity,
+  cashflow or incomestatement reports.
+
+  Now you can use your preferred account names, and use account directives
+  to declare which accounting class (Asset, Liability, Equity, Revenue or
+  eXpense) an account (and its subaccounts) belongs to, by writing one of
+  the letters A, L, E, R, X after the account name, after two or more
+  spaces. This syntax may change (see issue).  Experimental.
+
+  Currently we allow unlimited account type declarations anywhere in the
+  account tree. So you could declare a liability account somewhere under
+  assets, and maybe a revenue account under that, and another asset account
+  even further down. In such cases you start to see oddities like accounts
+  appearing in multiple places in a tree-mode report. I have left it this
+  way for now in case it helps with, eg, modelling contra accounts, or
+  combining multiple files each with their own account type
+  declarations. (In that scenario, if we only allowed type declarations on
+  top-level accounts, or only allowed a single account of each type,
+  complications seem likely.)
+
+* journal format: periodic transaction rules now require a double space separator.  
+  In periodic transaction rules which specify a transaction description or
+  same-line transaction comment, this must be separated from the period
+  expression by two or more spaces, to prevent ambiguous parsing. Eg
+  this will parse correctly as "monthly" thanks to the double space:
+
+      ~ monthly  In 2020 we'll end this monthly transaction.
+
+* journal format: exact/complete balance assertions (Samuel May).  
+  A stronger kind of balance assertion, written with a double equals sign,
+  asserts an account's complete account balance, not just the balance in
+  one commodity. (But only if it is a single-commodity balance, for now.)
+  Eg:
+
+      1/1
+        (a)  A 1
+        (a)  B 1
+        (a)  0   =  A 1   ; commodity A balance assertion, succeeds
+        (a)  0   == A 1   ; complete balance assertion, fails
+
+* journal format: account directives now allow whitespace or a comment after the account name  
+
+* journal format: using ~ for home directory in include directives now works (#896) (Mykola Orliuk)  
+
+* journal format: prevent misleading parse error messages with cyclic include directives (#853) (Alex Chen)  
+
+* journal format: transaction modifier multipliers handle total-priced amounts correctly (#928).  
+  Multipliers (*N) in transaction modifier rules did not multiply
+  total-priced amounts properly.  Now the total prices are also multiplied,
+  keeping the transaction balanced.
+
+* journal format: do amount inference/balance assignments/assertions before transaction modifiers (#893, #908) (Jesse Rosenthal)  
+  Previously, transaction modifier (auto postings) rules were applied
+  before missing amounts were inferred. This meant amount multipliers could
+  generate too many missing-amount postings, making the transaction
+  unbalanceable (#893).
+
+  Now, missing amount inference (and balance assignments, and balance
+  assertions, which are interdependent) are done earlier, before
+  transaction modifier rules are applied (#900, #903).
+
+  Also, we now disallow the combination of balance assignments and
+  transaction modifier rules which both affect the same account, which
+  could otherwise cause confusing balance assertion failures (#912).
+  (Because assignments now generate amounts to satisfy balance assertions
+  before transaction modifier rules are applied (#908).)
+
+* journal format: periodic transaction rules are now aware of Y default year directives. (#892)  
+  Ie when a default year Y is in effect, they resolve partial or relative
+  dates using Y/1/1 as the reference date, rather than today's date.
+
+hledger-ui 1.12
+
+* fix "Any" build error with GHC < 8.4  
+
+* error screen: always show error position properly (#904) (Mykola Orliuk)  
+
+* accounts screen: show correct balances when there's only periodic transactions  
+
+* drop the --status-toggles flag  
+
+* periodic transactions and transaction modifiers are always enabled.  
+  Rule-based transactions and postings are always generated
+  (--forecast and --auto are always on).
+  Experimental.
+
+* escape key resets to flat mode.  
+  Flat mode is the default at startup. Probably it should reset to tree
+  mode if --tree was used at startup.
+
+* tree mode tweaks: add --tree/-T/-F flags, make flat mode the default,    
+  toggle tree mode with T, ensure a visible effect on register screen
+
+* hide future txns by default, add --future flag, toggle with F.  
+  You may have transactions dated later than today, perhaps piped from
+  print --forecast or recorded in the journal, which you don't want to
+  see except when forecasting.
+
+  By default, we now hide future transactions, showing "today's balance".
+  This can be toggled with the F key, which is easier than setting a
+  date query. --present and --future flags have been added to set the
+  initial mode.
+
+  (Experimental. Interactions with date queries have not been explored.)
+
+* quick help tweaks; try to show most useful info first  
+
+* reorganise help dialog, fit content into 80x25 again  
+
+* styling tweaks; cyan/blue -> white/yellow  
+
+* less noisy styling in horizontal borders (#838)  
+
+* register screen: positive amounts: green -> black  
+  The green/red scheme helped distinguish the changes column from the
+  black/red balance column, but the default green is hard to read on
+  the pale background in some terminals. Also the changes column is
+  non-bold now.
 
 
-Install
+Getting started:
--------
+----------------
 
 All install methods are described at http://hledger.org/download .
 You can download windows binaries, or use a package manager, though in
@@ -28,25 +171,23 @@ some cases these will install an older hledger version.
 
 You can build the latest hledger packages with stack:
 
-$ stack install --resolver=lts-12 cassava-megaparsec-1.0.0 hledger-lib-1.11 
+$ stack install --resolver=lts-12 megaparsec-7.0.4
-  hledger-1.11 [hledger-ui-1.11] [hledger-web-1.11] [hledger-api-1.11]
+  cassava-megaparsec-2.0.0 config-ini-0.2.3.0 hledger-lib-1.12
+  hledger-1.12 [hledger-ui-1.12] [hledger-web-1.12] [hledger-api-1.12]
 
 or with cabal:
 
-$ cabal update && cabal install hledger-1.11 [hledger-ui-1.11] 
+$ cabal update && cabal install hledger-1.12 [hledger-ui-1.12] 
-  [hledger-web-1.11] [hledger-api-1.11]
+  [hledger-web-1.12] [hledger-api-1.12]
 
-If you don't have stack or cabal, or if you are having trouble,
+or with the hledger installer, on systems with bash installed
-on systems with bash installed (mac, linux, unix-like windows..)
+(handy if you don't have a working stack or cabal):
-hledger-install.sh is an easy and reliable way to get the latest hledger:
 
 $ curl -s https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh > hledger-install.sh
 $ less hledger-install.sh  # satisfy yourself that the script is safe
 $ bash hledger-install.sh
 
-
+Some commands to try:
-Getting started
----------------
 
 $ hledger add           # record some transactions, with guidance
 $ hledger print         # show recorded transactions
@@ -55,11 +196,10 @@ $ hledger -h            # show quick help
 $ hledger               # list available commands
 $ hledger help          # list built-in manuals
 
-To get oriented, see the tutorials and manuals at http://hledger.org .
+To get oriented, see the tutorials and manuals at http://hledger.org ;
-To get help, say hello and ask questions in the #hledger IRC channel
+say hello and ask questions in the #hledger IRC channel on Freenode, 
-on Freenode, accessible at http://irc.hledger.org .
+accessible at http://irc.hledger.org .
-New users and all forms of help are always welcome!
+New users and contributors are always welcome!
-
 
 Best,
 -Simon