X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=HACKING;h=04c25172e63644cd27427854cc749698a3799591;hb=6a88cfad209417cef169d4cb52a25d7d7071a7b5;hp=0d9f68e3b5e3562ad3df8e7675dbc47058112625;hpb=af4509909beb1cb175aa30fd6d24f43e334fa991;p=sup

diff --git a/HACKING b/HACKING
index 0d9f68e..04c2517 100644
--- a/HACKING
+++ b/HACKING
@@ -1,50 +1,42 @@
-Running Sup locally
--------------------
+Running Sup from your git checkout
+----------------------------------
+
 Invoke it like this:
 
-ruby -I lib -w bin/sup
+  ruby -I lib -w bin/sup
+
+You'll have to install all gems mentioned in the Rakefile (look for the line
+setting p.extra_deps). If you're on a Debian or Debian-based system (e.g.
+Ubuntu), you'll have to make sure you have a complete Ruby installation,
+especially libssl-ruby. You will need libruby-devel, gcc, and make installed
+to build certain gems like Ferret. Gem install does not do a good job of
+detecting when these things are missing and the build fails.
+
+Rubygems also is particularly aggressive about picking up libraries from
+installed gems. If you do have Sup installed as a gem, please examine
+backtraces to make sure you're loading files from the repository and NOT from
+the installed gem before submitting any bug reports.
 
 Coding standards
 ----------------
 
-- Don't wrap code unless it really benefits from it. The days of
-  80-column displays are long over. But do wrap comments and other
-  text at whatever Emacs meta-Q does.
-- Use as few parentheses as possible.
+- Don't wrap code unless it really benefits from it.
+- Do wrap comments at 72 characters.
+- Old lisp-style comment differentiations:
+   # one for comments on the same line as a line of code
+   ## two for comments on their own line, except:
+   ### three for comments that demarcate large sections of code (rare)
 - Use {} for one-liner blocks and do/end for multi-line blocks.
-
-How messages are updated in the index
--------------------------------------
-
-Ferret doesn't have any concept of updating; to change message state
-it must be deleted then re-added to the index.
-
-Thus there are a couple situations where we'll have a message to be
-"added", but it already exists in the index, and we need to decide
-which parts of which version to keep:
-
-1. The user has changed the state of the message, e.g. read it or
-   added a user label. In this case we want to use the state of the
-   version in memory, but keep everything else on disk.
-
-   This is the behavior of Index#update_message
-
-2. We've received a new copy of the message. Crucially, this can
-   happen for two different reasons:
-
-   a. The message was sent to a mailing list to which the user is
-      subscribed, and we're now getting that message back, possibly
-      with altered content (subject mangling, signature adding, etc.)
-
-   b. The user has moved the message between sources. E.g. if the
-      primary inbox has a quota, and other sources are on local,
-      quota-less disk, the user may regularly move messages from the
-      inbox to the sources on disk.
-
-   In both of these cases, the solution is to keep the state from the
-   index, but use the new message contents.
-
-   This is the behavior of Index#update_or_add_message, which can be
-   also be called for new message.
-
-
+- I like poetry mode. Don't use parentheses unless you must.
+- The one exception to poetry mode is if-statements that have an assignment in
+  the condition. To make it clear this is not a comparison, surround the
+  condition by parentheses. E.g.:
+    if a == b                    if(a = some.computation)
+      ...             BUT          ... something with a
+    end                          end
+- and/or versus ||/&&. In Ruby, "and" and "or" bind very loosely---even
+  more loosely than function application. This makes them ideal for
+  end-of-line short-circuit control in poetry mode. So, use || and &&
+  for ordinary logical comparisons, and "and" and "or" for end-of-line
+  flow control. E.g.:
+    x = a || b or raise "neither is true"