diff options
author | Marko Kreen | 2009-04-09 13:58:07 +0000 |
---|---|---|
committer | Marko Kreen | 2009-04-13 13:40:16 +0000 |
commit | 415cdc7929660fbf39e7f5ba64cb801f48b79bb2 (patch) | |
tree | 76efae92b1af2cefa2b95a37814687a194979229 | |
parent | 48f8ba60de975b17022096814eb8d8173eccc07a (diff) |
docs: more updates
New devnotes.txt to help developers.
-rw-r--r-- | AUTHORS | 1 | ||||
-rw-r--r-- | doc/Makefile | 2 | ||||
-rw-r--r-- | doc/devnotes.txt | 137 | ||||
-rw-r--r-- | doc/skytools3.txt | 26 |
4 files changed, 162 insertions, 4 deletions
@@ -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 --------------- |