summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarko Kreen2009-04-09 13:58:07 +0000
committerMarko Kreen2009-04-13 13:40:16 +0000
commit415cdc7929660fbf39e7f5ba64cb801f48b79bb2 (patch)
tree76efae92b1af2cefa2b95a37814687a194979229
parent48f8ba60de975b17022096814eb8d8173eccc07a (diff)
docs: more updates
New devnotes.txt to help developers.
-rw-r--r--AUTHORS1
-rw-r--r--doc/Makefile2
-rw-r--r--doc/devnotes.txt137
-rw-r--r--doc/skytools3.txt26
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
---------------