Coding Style
Python
Standard Python style with 4-space indent, no tabs.
C
-
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.git
$ cd skytools
$ git submodule init
$ git submodule update
Repos
Master Skytools repository: git://github.com/markokr/skytools.git
Master libusual repository: `git://github.com/markokr/libusual.git
Currently known developer repos are on github.com:
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
Initial setup
$ git config --global user.name "Marko Kreen"
$ git config --global user.email "markokr@gmail.com"
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
## make log nicer
$ git config --global log.decorate short
$ git config --global log.abbrevCommit true
Optional: activate tab-completion for git, pick one of the lines below
and put it into your .bashrc
:
# 1) use unpacked source tree
source $git_src_tree/contrib/completion/git-completion.bash
# 2) use packaged git (preferred)
source /etc/bash_completion.d/git
# 3) 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)")\$ '
Developement tasks
First, do the initial cloning as described above.
Add your own writable repo, named self:
$ cd skytools
$ git remote add self git@github.com:${username}/skytools.git
Push initial contents into it:
$ git push self master
Fetch changes from upstream repo into branch origin/master, but do not merge into local master:
$ git fetch origin
See changes in upstream repo:
$ git log [-p] origin/master
Merge changes from upstream repo into currently checked out branch:
$ git merge origin/master
Alternative: do fetch+merge in one go (assuming you are in master branch):
$ git pull
Commit a change, push to your repo (on master branch):
$ edit oldfile
$ edit newfile
$ git add newfile
$ git commit -a -m '..'
$ git push self master
Create a branch for your changes, starting from checked out branch
$ git branch mybranch
$ git checkout mybranch
## or, in one command
$ git checkout -b mybranch
Commit files
$ edit oldfile
$ edit newfile
$ git add newfile
$ git commit -a -m 'commit summary'
## optional: merge, or update commits relative to master branch
$ git rebase -i master
## merge into master
$ git checkout master
$ git merge mybranch
Push changes into your own public repo:
$ git push self master