1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
= 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.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:
* 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 ===
==== 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
## 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 [email protected]:${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
|
