docs: more updates

New devnotes.txt to help developers.

4 files changed, 162 insertions, 4 deletions

diff --git a/AUTHORS b/AUTHORS
index 768a4083..676805dd 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -8,6 +8,7 @@ Contributors
 André Malo
 Andrew Dunstan
 Asko Oja
+Asko Tiidumaa
 Charles Duffy
 Devrim Gündüz
 Dimitri Fontaine
diff --git a/doc/Makefile b/doc/Makefile
index a9e1bc9c..eaa13acf 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -11,7 +11,7 @@ EPYARGS = --no-private --url="http://pgfoundry.org/projects/skytools/" \
 
 HTMLS = londiste.cmdline.html londiste.config.html README.html INSTALL.html \
 	londiste.ref.html TODO.html pgq-sql.html pgq-admin.html pgq-nodupes.html \
-	$(SCRIPT_HTMLS) faq.html set.notes.html newadm.html skytools3.html
+	$(SCRIPT_HTMLS) faq.html set.notes.html newadm.html skytools3.html devnotes.html
 
 SCRIPT_TXTS = walmgr.txt cube_dispatcher.txt table_dispatcher.txt \
 	      queue_mover.txt queue_splitter.txt bulk_loader.txt \
diff --git a/doc/devnotes.txt b/doc/devnotes.txt
new file mode 100644
index 00000000..0a5f73bc
--- /dev/null
+++ b/doc/devnotes.txt
@@ -0,0 +1,137 @@
+= Notes for developers =
+
+== Coding Style ==
+
+=== Python ===
+
+Standard Python style with 4-space indent, no tabs.
+
+* http://python.org/dev/peps/pep-0008/[PEP-8: Style Guide to Python Code]
+* http://www.python.org/dev/peps/pep-0257/[PEP-257: Docstring conventions]
+
+=== C ===
+
+* http://lxr.linux.no/linux/Documentation/CodingStyle[Linux kernel style] - K&R with 8-space tabs.
+* Target is modern C (c99) - vararg macros, struct field initializers are OK.
+* `static inline` is perferred to macros.
+
+There may be couple places still using the historical Postgres
+style with half-tength tabs.  Please follow if doing small patches
+to those files.  For bigger work it may be preferable to reindent
+the file.
+
+=== SQL ===
+
+* Indent with 4 spaces.
+* All-lowercase (expecting syntax highlighing editor).
+* We use NaturalDocs for API documentation, see existing code
+  for examples.
+* Functions should use OUT parameters instead of return types.
+* Local variables should prefixed with '_'.
+* Database clients should not access tables directly but
+  do operations via functions.  (Except when script's task
+  is to replicate tables.)
+* Any sort of comma-first style is forbidden.  Code should
+  be optimized for reading not writing.
+
+
+== Patches ==
+
+Although the developemt happens in GIT repos, the contributors
+are not required to publish their changes via GIT, sending
+patches is fine.  The preferred patch format is unified diff,
+which is the default for git:
+
+  $ git diff > patch
+
+or with plain `diff`:
+
+  $ diff -ur skytools-2.1.9 skytools-my > patch
+
+
+== GIT usage ==
+
+=== Initial cloning ===
+
+libusual is used as git subproject, so after inital clone
+submodule update should be done:
+
+  $ git clone git://github.com/markokr/skytools-dev.git
+  $ cd skytools-dev
+  $ git submodule init
+  $ git submodule update
+
+=== Repos ===
+
+Master Skytools repository: `git://github.com/markokr/skytools-dev.git`
+Master libusual repository: `git://github.com/markokr/libusual.git`
+
+Currently known developer repos are on github.com:
+
+* http://github.com/markokr[]
+* http://github.com/mpihlak[]
+
+
+=== Commit style ===
+
+GIT expects first line of commit message to be short summary,
+rest of the message in-depth explanation about commit.
+The short summary is used by `git shortlog`, `gitk` and
+various web-interfaces.
+
+So the commit message should be written in email style -
+first a subject line, empty line then longer details.
+
+Short summary should also contain component name or subdir
+that the commit touches:
+
+    ---------------------------------
+    sql/pgq: reindent C code
+    
+    Several places had whitespace bugs, probably due to copy-paste.
+    
+    As there is no point keeping historical PG style around here,
+    reindent with proper -kr -i8.
+    ---------------------------------
+
+=== Developer workflow ===
+
+FIXME: no workflow suggestions yet, ATM just describe how
+to set up comfortable environment.
+
+==== Initial setup ====
+
+  $ git config --global user.name "Marko Kreen"
+  $ git config --global user.email "[email protected]"
+
+Optional: make git colorful:
+
+  ## make 'less' accept color codes
+  $ export PAGER=less
+  $ export LESS="-R"     # markokr: LESS="-RgQnh2"
+
+  ## make git use color
+  $ git config --global color.branch auto
+  $ git config --global color.diff auto
+  $ git config --global color.pager true
+  $ git config --global color.status true
+
+Optional: activate tab-completion for git, pick one of the lines below
+and put it into your `.bashrc`:
+
+  # use unpacked source tree
+  source $git_src_tree/contrib/completion/git-completion.bash
+  
+  # use packaged git
+  source /etc/bash_completion.d/git
+
+  # use packaged git, turn extended completion for everything
+  # [ markokr: buggy completion modules can be rather annoying
+  #   so it may be preferable to activate them one-by-one ]
+  source /etc/bash_completion
+
+Optional: show current checked out branch in bash prompt,
+requires the completion script from above:
+
+  PS1='\h:\w$(__git_ps1 " (%s)")\$ '
+
diff --git a/doc/skytools3.txt b/doc/skytools3.txt
index b099d5a1..a1ec0188 100644
--- a/doc/skytools3.txt
+++ b/doc/skytools3.txt
@@ -23,6 +23,7 @@ New features in Skytools 3
   - Its goal is to keep identical copy of queue contents in several nodes.
   - Not replication-specific - can be used for any queue.
   - Advanced admin operations: switchover, failover, change-provider, pause/resume.
+  - For terminology and technical details see here: set.notes.txt.
 
 * New Londiste features:
   - Parallel copy - during inital sync several tables can be
@@ -97,19 +98,38 @@ Open questions
 
 * Python modules
   - Skytools 3 modules should be parallel installable with Skytools 2.
-    we decided to solve it via loader module (pygtk does).  The question
-    is 
+    we decided to solve it via loader module
+    (like http://faq.pygtk.org/index.py?req=all#2.4[pygtk]).
+    The question is should we have Skytools-specific loader or more generic.
+    And what should the name be?
+
+      import skytools_loader
+      skytools_loader.require('3.0')
+
+      vs
+
+      import pkgloader
+      pkgloader.require('skytools', '3.0')
 
 * PgQ Cascading
   - There are some periodic operations that should be done on root node.
     Should we let the ticker do them or do we require a Londiste daemon there?
+    Letting ticker do it means initial setup is slightly easier.
+    But requiring separate daemon means user has guarantee that
+    switchover (downgrading root to branch) works without need to
+    start the replication daemon.
 
 * Londiste EXECUTE command
-  - Should the scripts have some sort of 
+  - Should the scripts have ability to inform Londiste of the tables
+    they operate on, so that nodes that do not have such tables
+    can ignore the script.
 
 * Newadm:
   - Good name for it.
 
+* Is there good reason not to drop following modules:
+  - logtriga(), pgq.logtriga() - non-automatic triggers
+  - cube_dispatcher, table_dispatcher, bulk_loader - they are merged into queue_loader
 
 Further reading
 ---------------