head	1.148;
access;
symbols
	REL7_4_29:1.55.2.3
	REL8_0_25:1.81.4.8
	REL8_1_21:1.99.2.6
	REL8_2_17:1.117.2.4
	REL8_3_11:1.146.2.1
	REL7_4_28:1.55.2.3
	REL8_0_24:1.81.4.8
	REL8_1_20:1.99.2.6
	REL8_2_16:1.117.2.4
	REL8_3_10:1.146.2.1
	REL7_4_27:1.55.2.3
	REL8_0_23:1.81.4.8
	REL8_1_19:1.99.2.6
	REL8_2_15:1.117.2.4
	REL8_3_9:1.146.2.1
	REL7_4_26:1.55.2.3
	REL8_0_22:1.81.4.8
	REL8_1_18:1.99.2.6
	REL8_2_14:1.117.2.4
	REL8_3_8:1.146.2.1
	REL7_4_25:1.55.2.3
	REL8_0_21:1.81.4.8
	REL8_1_17:1.99.2.6
	REL8_2_13:1.117.2.4
	REL8_3_7:1.146.2.1
	REL7_4_24:1.55.2.3
	REL8_0_20:1.81.4.8
	REL8_1_16:1.99.2.6
	REL8_2_12:1.117.2.4
	REL8_3_6:1.146.2.1
	REL7_4_23:1.55.2.3
	REL8_0_19:1.81.4.8
	REL8_1_15:1.99.2.6
	REL8_2_11:1.117.2.4
	REL8_3_5:1.146.2.1
	REL7_4_22:1.55.2.3
	REL8_0_18:1.81.4.8
	REL8_1_14:1.99.2.6
	REL8_2_10:1.117.2.4
	REL8_3_4:1.146.2.1
	REL7_4_21:1.55.2.3
	REL8_0_17:1.81.4.8
	REL8_1_13:1.99.2.6
	REL8_2_9:1.117.2.4
	REL8_3_3:1.146.2.1
	REL7_4_20:1.55.2.3
	REL8_0_16:1.81.4.8
	REL8_1_12:1.99.2.6
	REL8_2_8:1.117.2.4
	REL8_3_2:1.146.2.1
	REL8_2_7:1.117.2.3
	REL8_3_1:1.146
	REL8_3_STABLE:1.146.0.2
	REL8_3_0:1.146
	REL8_3_RC2:1.146
	REL7_3_21:1.47.2.3
	REL7_4_19:1.55.2.2
	REL8_0_15:1.81.4.7
	REL8_1_11:1.99.2.5
	REL8_2_6:1.117.2.3
	REL8_3_RC1:1.146
	REL8_3_BETA4:1.146
	REL8_3_BETA3:1.146
	REL8_3_BETA2:1.145
	REL8_3_BETA1:1.143
	REL7_3_20:1.47.2.3
	REL7_4_18:1.55.2.2
	REL8_0_14:1.81.4.7
	REL8_1_10:1.99.2.5
	REL8_2_5:1.117.2.3
	REL7_3_19:1.47.2.3
	REL7_4_17:1.55.2.2
	REL8_0_13:1.81.4.7
	REL8_1_9:1.99.2.5
	REL8_2_4:1.117.2.2
	REL8_0_12:1.81.4.7
	REL8_1_8:1.99.2.5
	REL8_2_3:1.117.2.1
	REL7_3_18:1.47.2.3
	REL7_4_16:1.55.2.2
	REL8_0_11:1.81.4.7
	REL8_1_7:1.99.2.5
	REL8_2_2:1.117.2.1
	REL8_0_10:1.81.4.7
	REL8_1_6:1.99.2.5
	REL8_2_1:1.117.2.1
	REL7_4_15:1.55.2.2
	REL7_3_17:1.47.2.3
	REL8_2_STABLE:1.117.0.2
	REL8_2_0:1.117
	REL8_2_RC1:1.117
	REL8_2_BETA3:1.116
	REL8_2_BETA2:1.116
	REL8_1_5:1.99.2.5
	REL8_0_9:1.81.4.7
	REL7_4_14:1.55.2.2
	REL7_3_16:1.47.2.3
	REL8_2_BETA1:1.114
	REL7_3_15:1.47.2.3
	REL7_4_13:1.55.2.2
	REL8_0_8:1.81.4.7
	REL8_1_4:1.99.2.4
	REL7_3_14:1.47.2.3
	REL7_4_12:1.55.2.2
	REL8_0_7:1.81.4.7
	REL8_1_3:1.99.2.2
	REL7_3_13:1.47.2.3
	REL7_4_11:1.55.2.2
	REL8_0_6:1.81.4.7
	REL8_1_2:1.99.2.2
	REL7_3_12:1.47.2.3
	REL7_4_10:1.55.2.2
	REL8_0_5:1.81.4.7
	REL8_1_1:1.99.2.1
	REL8_1_STABLE:1.99.0.2
	REL8_1_0:1.99
	REL8_1_0RC1:1.99
	REL8_1_0BETA4:1.98
	REL8_1_0BETA3:1.98
	REL7_3_11:1.47.2.3
	REL7_4_9:1.55.2.2
	REL8_0_4:1.81.4.6
	REL8_1_0BETA2:1.97
	REL8_1_0BETA1:1.97
	REL7_2_8:1.37
	REL7_3_10:1.47.2.3
	REL7_4_8:1.55.2.2
	REL8_0_3:1.81.4.3
	REL8_0_2:1.81.4.2
	REL7_2_7:1.37
	REL7_3_9:1.47.2.3
	REL7_4_7:1.55.2.2
	REL8_0_1:1.81
	REL8_0_STABLE:1.81.0.4
	REL8_0_0:1.81.0.2
	REL8_0_0RC5:1.81
	REL8_0_0RC4:1.81
	REL8_0_0RC3:1.78
	REL8_0_0RC2:1.78
	REL8_0_0RC1:1.78
	REL8_0_0BETA5:1.76
	REL8_0_0BETA4:1.76
	REL7_4_6:1.55.2.2
	REL7_3_8:1.47.2.3
	REL7_2_6:1.37
	REL8_0_0BETA3:1.62
	REL8_0_0BETA2:1.62
	REL7_2_5:1.37
	REL7_4_5:1.55.2.2
	REL7_3_7:1.47.2.3
	REL7_4_4:1.55.2.2
	REL8_0_0BETA1:1.62
	REL7_4_3:1.55.2.2
	REL7_4_2:1.55.2.2
	REL7_3_6:1.47.2.3
	REL7_4_1:1.55.2.1
	REL7_3_5:1.47.2.3
	REL7_4:1.55
	REL7_4_RC2:1.55
	REL7_4_STABLE:1.55.0.2
	REL7_4_RC1:1.55
	REL7_4_BETA5:1.54
	REL7_4_BETA4:1.54
	REL7_4_BETA3:1.54
	REL7_4_BETA2:1.54
	WIN32_DEV:1.54.0.2
	REL7_4_BETA1:1.54
	REL7_3_4:1.47.2.3
	REL7_3_2:1.47.2.1
	REL7_2_4:1.37
	REL7_3_STABLE:1.47.0.2
	REL7_2_3:1.37
	REL7_2_STABLE:1.37.0.2
	REL7_2:1.37
	REL7_2_RC2:1.36
	REL7_2_RC1:1.36
	REL7_2_BETA5:1.36
	REL7_2_BETA4:1.30
	REL7_2_BETA3:1.16
	REL7_2_BETA2:1.16
	REL7_2_BETA1:1.16
	REL7_1_2:1.15
	REL7_1_STABLE:1.15.0.2
	REL7_1_BETA:1.13
	REL7_1_BETA3:1.15
	REL7_1_BETA2:1.15
	REL7_1:1.15
	REL7_0_PATCHES:1.7.0.2
	REL7_0:1.7
	REL6_5_PATCHES:1.5.0.2
	REL6_5:1.5
	REL6_4:1.3.0.2;
locks; strict;
comment	@# @;


1.148
date	2009.04.07.21.20.49;	author momjian;	state dead;
branches;
next	1.147;

1.147
date	2008.04.22.09.26.32;	author mha;	state Exp;
branches;
next	1.146;

1.146
date	2007.11.14.03.39.17;	author momjian;	state Exp;
branches
	1.146.2.1;
next	1.145;

1.145
date	2007.10.26.19.08.57;	author momjian;	state Exp;
branches;
next	1.144;

1.144
date	2007.10.09.01.28.24;	author momjian;	state Exp;
branches;
next	1.143;

1.143
date	2007.09.26.20.38.27;	author momjian;	state Exp;
branches;
next	1.142;

1.142
date	2007.09.23.18.06.47;	author momjian;	state Exp;
branches;
next	1.141;

1.141
date	2007.08.23.00.10.07;	author momjian;	state Exp;
branches;
next	1.140;

1.140
date	2007.08.23.00.09.34;	author momjian;	state Exp;
branches;
next	1.139;

1.139
date	2007.07.17.05.03.55;	author momjian;	state Exp;
branches;
next	1.138;

1.138
date	2007.06.01.04.11.43;	author momjian;	state Exp;
branches;
next	1.137;

1.137
date	2007.06.01.04.05.35;	author momjian;	state Exp;
branches;
next	1.136;

1.136
date	2007.06.01.00.28.34;	author momjian;	state Exp;
branches;
next	1.135;

1.135
date	2007.05.05.14.33.55;	author momjian;	state Exp;
branches;
next	1.134;

1.134
date	2007.05.05.14.31.16;	author momjian;	state Exp;
branches;
next	1.133;

1.133
date	2007.05.05.10.21.13;	author momjian;	state Exp;
branches;
next	1.132;

1.132
date	2007.05.05.04.09.25;	author momjian;	state Exp;
branches;
next	1.131;

1.131
date	2007.03.19.16.53.03;	author momjian;	state Exp;
branches;
next	1.130;

1.130
date	2007.03.05.18.04.02;	author momjian;	state Exp;
branches;
next	1.129;

1.129
date	2007.03.03.16.12.37;	author momjian;	state Exp;
branches;
next	1.128;

1.128
date	2007.03.02.21.03.55;	author momjian;	state Exp;
branches;
next	1.127;

1.127
date	2007.03.02.21.03.11;	author momjian;	state Exp;
branches;
next	1.126;

1.126
date	2007.03.02.17.51.56;	author momjian;	state Exp;
branches;
next	1.125;

1.125
date	2007.02.28.17.28.09;	author momjian;	state Exp;
branches;
next	1.124;

1.124
date	2007.02.27.23.12.50;	author momjian;	state Exp;
branches;
next	1.123;

1.123
date	2007.02.27.21.07.20;	author momjian;	state Exp;
branches;
next	1.122;

1.122
date	2007.02.19.23.45.38;	author momjian;	state Exp;
branches;
next	1.121;

1.121
date	2007.01.04.21.00.13;	author momjian;	state Exp;
branches;
next	1.120;

1.120
date	2006.12.22.22.42.36;	author momjian;	state Exp;
branches;
next	1.119;

1.119
date	2006.12.20.16.22.14;	author momjian;	state Exp;
branches;
next	1.118;

1.118
date	2006.12.19.22.37.37;	author momjian;	state Exp;
branches;
next	1.117;

1.117
date	2006.11.14.04.18.55;	author momjian;	state Exp;
branches
	1.117.2.1;
next	1.116;

1.116
date	2006.10.17.12.54.45;	author momjian;	state Exp;
branches;
next	1.115;

1.115
date	2006.10.16.19.03.43;	author momjian;	state Exp;
branches;
next	1.114;

1.114
date	2006.09.07.00.12.20;	author momjian;	state Exp;
branches;
next	1.113;

1.113
date	2006.09.07.00.08.43;	author momjian;	state Exp;
branches;
next	1.112;

1.112
date	2006.09.06.22.03.22;	author momjian;	state Exp;
branches;
next	1.111;

1.111
date	2006.08.12.03.48.32;	author momjian;	state Exp;
branches;
next	1.110;

1.110
date	2006.08.11.19.18.59;	author momjian;	state Exp;
branches;
next	1.109;

1.109
date	2006.07.11.17.02.16;	author momjian;	state Exp;
branches;
next	1.108;

1.108
date	2006.06.18.19.34.00;	author momjian;	state Exp;
branches;
next	1.107;

1.107
date	2006.06.08.13.45.35;	author momjian;	state Exp;
branches;
next	1.106;

1.106
date	2006.05.05.09.51.53;	author momjian;	state Exp;
branches;
next	1.105;

1.105
date	2006.03.01.22.24.51;	author momjian;	state Exp;
branches;
next	1.104;

1.104
date	2005.12.24.19.29.38;	author momjian;	state Exp;
branches;
next	1.103;

1.103
date	2005.12.24.18.37.17;	author momjian;	state Exp;
branches;
next	1.102;

1.102
date	2005.11.22.15.17.57;	author momjian;	state Exp;
branches;
next	1.101;

1.101
date	2005.11.22.15.17.05;	author momjian;	state Exp;
branches;
next	1.100;

1.100
date	2005.11.22.15.13.02;	author momjian;	state Exp;
branches;
next	1.99;

1.99
date	2005.10.27.13.48.14;	author momjian;	state Exp;
branches
	1.99.2.1;
next	1.98;

1.98
date	2005.09.20.01.28.14;	author momjian;	state Exp;
branches;
next	1.97;

1.97
date	2005.08.09.04.56.57;	author momjian;	state Exp;
branches;
next	1.96;

1.96
date	2005.05.14.16.26.17;	author momjian;	state Exp;
branches;
next	1.95;

1.95
date	2005.05.11.16.13.19;	author momjian;	state Exp;
branches;
next	1.94;

1.94
date	2005.05.06.17.48.03;	author momjian;	state Exp;
branches;
next	1.93;

1.93
date	2005.04.23.20.52.32;	author momjian;	state Exp;
branches;
next	1.92;

1.92
date	2005.04.23.18.57.46;	author momjian;	state Exp;
branches;
next	1.91;

1.91
date	2005.03.14.03.07.25;	author momjian;	state Exp;
branches;
next	1.90;

1.90
date	2005.03.13.19.27.53;	author momjian;	state Exp;
branches;
next	1.89;

1.89
date	2005.03.11.21.43.27;	author momjian;	state Exp;
branches;
next	1.88;

1.88
date	2005.03.11.13.09.39;	author momjian;	state Exp;
branches;
next	1.87;

1.87
date	2005.03.11.11.59.16;	author momjian;	state Exp;
branches;
next	1.86;

1.86
date	2005.03.11.11.43.45;	author momjian;	state Exp;
branches;
next	1.85;

1.85
date	2005.03.11.11.42.02;	author momjian;	state Exp;
branches;
next	1.84;

1.84
date	2005.03.08.13.27.31;	author momjian;	state Exp;
branches;
next	1.83;

1.83
date	2005.03.08.03.52.57;	author momjian;	state Exp;
branches;
next	1.82;

1.82
date	2005.03.08.01.15.33;	author momjian;	state Exp;
branches;
next	1.81;

1.81
date	2005.01.05.22.37.25;	author momjian;	state Exp;
branches
	1.81.4.1;
next	1.80;

1.80
date	2005.01.05.17.52.21;	author momjian;	state Exp;
branches;
next	1.79;

1.79
date	2005.01.05.17.42.08;	author momjian;	state Exp;
branches;
next	1.78;

1.78
date	2004.12.01.17.21.57;	author momjian;	state Exp;
branches;
next	1.77;

1.77
date	2004.11.27.06.02.52;	author momjian;	state Exp;
branches;
next	1.76;

1.76
date	2004.10.15.16.27.06;	author momjian;	state Exp;
branches;
next	1.75;

1.75
date	2004.10.15.16.10.31;	author momjian;	state Exp;
branches;
next	1.74;

1.74
date	2004.10.14.21.47.14;	author momjian;	state Exp;
branches;
next	1.73;

1.73
date	2004.10.14.21.46.15;	author momjian;	state Exp;
branches;
next	1.72;

1.72
date	2004.10.14.21.39.14;	author momjian;	state Exp;
branches;
next	1.71;

1.71
date	2004.10.14.19.15.01;	author momjian;	state Exp;
branches;
next	1.70;

1.70
date	2004.10.14.19.13.08;	author momjian;	state Exp;
branches;
next	1.69;

1.69
date	2004.10.14.19.10.30;	author momjian;	state Exp;
branches;
next	1.68;

1.68
date	2004.10.14.19.08.39;	author momjian;	state Exp;
branches;
next	1.67;

1.67
date	2004.10.14.19.07.56;	author momjian;	state Exp;
branches;
next	1.66;

1.66
date	2004.10.14.19.04.19;	author momjian;	state Exp;
branches;
next	1.65;

1.65
date	2004.10.14.19.02.07;	author momjian;	state Exp;
branches;
next	1.64;

1.64
date	2004.10.14.19.00.41;	author momjian;	state Exp;
branches;
next	1.63;

1.63
date	2004.10.04.15.29.41;	author momjian;	state Exp;
branches;
next	1.62;

1.62
date	2004.07.19.20.30.16;	author momjian;	state Exp;
branches;
next	1.61;

1.61
date	2004.06.07.15.11.23;	author momjian;	state Exp;
branches;
next	1.60;

1.60
date	2004.04.07.23.32.30;	author momjian;	state Exp;
branches;
next	1.59;

1.59
date	2004.04.07.22.02.03;	author momjian;	state Exp;
branches;
next	1.58;

1.58
date	2004.04.07.14.23.32;	author momjian;	state Exp;
branches;
next	1.57;

1.57
date	2004.02.10.15.16.36;	author momjian;	state Exp;
branches;
next	1.56;

1.56
date	2003.11.30.04.56.47;	author momjian;	state Exp;
branches;
next	1.55;

1.55
date	2003.10.30.02.40.29;	author momjian;	state Exp;
branches
	1.55.2.1;
next	1.54;

1.54
date	2003.06.02.04.35.04;	author momjian;	state Exp;
branches;
next	1.53;

1.53
date	2003.02.19.01.38.41;	author momjian;	state Exp;
branches;
next	1.52;

1.52
date	2003.02.18.16.38.05;	author momjian;	state Exp;
branches;
next	1.51;

1.51
date	2003.02.14.13.59.14;	author momjian;	state Exp;
branches;
next	1.50;

1.50
date	2003.02.09.06.56.26;	author tgl;	state Exp;
branches;
next	1.49;

1.49
date	2002.11.05.21.53.24;	author momjian;	state Exp;
branches;
next	1.48;

1.48
date	2002.11.05.21.49.51;	author momjian;	state Exp;
branches;
next	1.47;

1.47
date	2002.11.03.04.02.32;	author momjian;	state Exp;
branches
	1.47.2.1;
next	1.46;

1.46
date	2002.09.07.18.39.04;	author momjian;	state Exp;
branches;
next	1.45;

1.45
date	2002.08.13.20.41.13;	author momjian;	state Exp;
branches;
next	1.44;

1.44
date	2002.08.13.20.40.43;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	2002.04.17.05.12.39;	author momjian;	state Exp;
branches;
next	1.42;

1.42
date	2002.04.17.05.10.09;	author momjian;	state Exp;
branches;
next	1.41;

1.41
date	2002.04.17.05.00.00;	author momjian;	state Exp;
branches;
next	1.40;

1.40
date	2002.04.17.02.10.21;	author momjian;	state Exp;
branches;
next	1.39;

1.39
date	2002.02.25.20.29.37;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	2002.02.23.20.09.39;	author momjian;	state Exp;
branches;
next	1.37;

1.37
date	2002.02.01.20.25.35;	author momjian;	state Exp;
branches;
next	1.36;

1.36
date	2002.01.03.08.20.53;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	2002.01.03.08.13.50;	author momjian;	state Exp;
branches;
next	1.34;

1.34
date	2001.12.30.04.31.29;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2001.12.29.05.15.42;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2001.12.29.05.12.45;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2001.12.29.03.42.58;	author momjian;	state Exp;
branches;
next	1.30;

1.30
date	2001.12.04.17.12.25;	author momjian;	state Exp;
branches;
next	1.29;

1.29
date	2001.12.04.06.37.29;	author momjian;	state Exp;
branches;
next	1.28;

1.28
date	2001.12.04.06.35.56;	author momjian;	state Exp;
branches;
next	1.27;

1.27
date	2001.12.04.06.26.59;	author momjian;	state Exp;
branches;
next	1.26;

1.26
date	2001.12.04.06.20.12;	author momjian;	state Exp;
branches;
next	1.25;

1.25
date	2001.12.04.06.14.44;	author momjian;	state Exp;
branches;
next	1.24;

1.24
date	2001.12.04.06.14.04;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2001.11.28.01.38.39;	author momjian;	state Exp;
branches;
next	1.22;

1.22
date	2001.11.28.01.20.27;	author momjian;	state Exp;
branches;
next	1.21;

1.21
date	2001.11.28.00.36.33;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2001.11.28.00.12.39;	author momjian;	state Exp;
branches;
next	1.19;

1.19
date	2001.11.27.17.51.54;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	2001.11.26.22.42.51;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	2001.11.26.22.41.58;	author momjian;	state Exp;
branches;
next	1.16;

1.16
date	2001.07.11.02.13.20;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	2000.12.09.04.57.31;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2000.12.09.04.29.42;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2000.11.16.22.30.13;	author tgl;	state Exp;
branches;
next	1.12;

1.12
date	2000.11.04.18.23.36;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2000.11.04.17.09.24;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	2000.06.10.02.05.25;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	2000.06.10.01.55.36;	author momjian;	state Exp;
branches;
next	1.8;

1.8
date	2000.06.09.01.43.55;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	99.12.24.16.46.11;	author momjian;	state Exp;
branches
	1.7.2.1;
next	1.6;

1.6
date	99.12.21.17.34.05;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	99.07.10.16.28.00;	author momjian;	state Exp;
branches
	1.5.2.1;
next	1.4;

1.4
date	99.06.05.03.43.04;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	98.10.24.04.43.38;	author momjian;	state Exp;
branches
	1.3.2.1;
next	1.2;

1.2
date	98.06.16.03.55.15;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	98.05.22.04.20.50;	author momjian;	state Exp;
branches;
next	;

1.3.2.1
date	98.12.18.05.25.56;	author momjian;	state Exp;
branches;
next	;

1.5.2.1
date	99.09.13.00.20.48;	author momjian;	state Exp;
branches;
next	;

1.7.2.1
date	2000.06.10.02.05.55;	author momjian;	state Exp;
branches;
next	;

1.47.2.1
date	2002.11.16.02.34.22;	author momjian;	state Exp;
branches;
next	1.47.2.2;

1.47.2.2
date	2003.02.14.14.05.51;	author momjian;	state Exp;
branches;
next	1.47.2.3;

1.47.2.3
date	2003.07.23.04.13.11;	author momjian;	state Exp;
branches;
next	;

1.55.2.1
date	2003.12.13.16.57.36;	author momjian;	state Exp;
branches;
next	1.55.2.2;

1.55.2.2
date	2004.03.05.19.57.20;	author momjian;	state Exp;
branches;
next	1.55.2.3;

1.55.2.3
date	2008.04.22.09.26.34;	author mha;	state Exp;
branches;
next	;

1.81.4.1
date	2005.03.11.21.47.35;	author momjian;	state Exp;
branches;
next	1.81.4.2;

1.81.4.2
date	2005.04.01.16.42.58;	author momjian;	state Exp;
branches;
next	1.81.4.3;

1.81.4.3
date	2005.05.09.17.24.03;	author momjian;	state Exp;
branches;
next	1.81.4.4;

1.81.4.4
date	2005.05.11.16.13.57;	author momjian;	state Exp;
branches;
next	1.81.4.5;

1.81.4.5
date	2005.05.16.02.50.58;	author momjian;	state Exp;
branches;
next	1.81.4.6;

1.81.4.6
date	2005.09.22.22.14.10;	author momjian;	state Exp;
branches;
next	1.81.4.7;

1.81.4.7
date	2005.11.05.01.36.41;	author momjian;	state Exp;
branches;
next	1.81.4.8;

1.81.4.8
date	2008.04.22.09.26.36;	author mha;	state Exp;
branches;
next	;

1.99.2.1
date	2005.12.08.21.37.53;	author momjian;	state Exp;
branches;
next	1.99.2.2;

1.99.2.2
date	2006.01.05.04.02.25;	author momjian;	state Exp;
branches;
next	1.99.2.3;

1.99.2.3
date	2006.03.01.22.25.36;	author momjian;	state Exp;
branches;
next	1.99.2.4;

1.99.2.4
date	2006.05.19.03.34.49;	author momjian;	state Exp;
branches;
next	1.99.2.5;

1.99.2.5
date	2006.10.10.00.29.13;	author momjian;	state Exp;
branches;
next	1.99.2.6;

1.99.2.6
date	2008.04.22.09.26.39;	author mha;	state Exp;
branches;
next	;

1.117.2.1
date	2007.01.05.20.55.28;	author momjian;	state Exp;
branches;
next	1.117.2.2;

1.117.2.2
date	2007.04.19.03.07.22;	author momjian;	state Exp;
branches;
next	1.117.2.3;

1.117.2.3
date	2007.09.11.17.37.29;	author momjian;	state Exp;
branches;
next	1.117.2.4;

1.117.2.4
date	2008.04.22.09.26.41;	author mha;	state Exp;
branches;
next	;

1.146.2.1
date	2008.04.22.09.26.45;	author mha;	state Exp;
branches;
next	;


desc
@@


1.148
log
@Remove FAQ and FAQ_DEV ASCII and HTML files from CVS;  now on the wiki.

Per-language files kept for transator usage.
@
text
@The developer FAQ can be found on the PostgreSQL wiki:

  http://wiki.postgresql.org/wiki/Development_information
@


1.147
log
@Replace developer FAQ with a reference to the wiki, which is where
it now lives (per discussion). Leave the other FAQs alone for now.
@
text
@@


1.146
log
@Reference pgfoundry instead of gborg.
@
text
@d1 1
d3 1
a3 838
          Developer's Frequently Asked Questions (FAQ) for PostgreSQL
                                       
   Last updated: Tue Nov 13 22:39:08 EST 2007
   
   Current maintainer: Bruce Momjian (bruce@@momjian.us)
   
   The most recent version of this document can be viewed at
   http://www.postgresql.org/docs/faqs.FAQ_DEV.html.
     _________________________________________________________________
   
General Questions

   1.1) How do I get involved in PostgreSQL development?
   1.2) What development environment is required to develop code?
   1.3) What areas need work?
   1.4) What do I do after choosing an item to work on?
   1.5) I have developed a patch, what next?
   1.6) How is a patch reviewed?
   1.7) Where can I learn more about the code?
   1.8) How do I download/update the current source tree?
   1.9) How do I test my changes?
   1.10) What tools are available for developers?
   1.11) What books are good for developers?
   1.12) What is configure all about?
   1.13) How do I add a new port?
   1.14) Why don't you use threads, raw devices, async-I/O, <insert your
   favorite wizz-bang feature here>?
   1.15) How are RPM's packaged?
   1.16) How are CVS branches handled?
   1.17) Where can I get a copy of the SQL standards?
   1.18) Where can I get technical assistance?
   1.19) How do I get involved in PostgreSQL web site development?
   1.20) Why haven't you replaced CVS with SVN, Git, Monotone, VSS,
   <insert your favorite SCM system here>?
   
Technical Questions

   2.1) How do I efficiently access information in tables from the
   backend code?
   2.2) Why are table, column, type, function, view names sometimes
   referenced as Name or NameData, and sometimes as char *?
   2.3) Why do we use Node and List to make data structures?
   2.4) I just added a field to a structure. What else should I do?
   2.5) Why do we use palloc() and pfree() to allocate memory?
   2.6) What is ereport()?
   2.7) What is CommandCounterIncrement()?
   2.8) What debugging features are available?
     _________________________________________________________________
   
General Questions

  1.1) How do I get involved in PostgreSQL development?
  
   Download the code and have a look around. See 1.8.
   
   Subscribe to and read the pgsql-hackers mailing list (often termed
   'hackers'). This is where the major contributors and core members of
   the project discuss development.
   
  1.2) What development environment is required to develop code?
  
   PostgreSQL is developed mostly in the C programming language. It also
   makes use of Yacc and Lex.
   
   The source code is targeted at most of the popular Unix platforms and
   the Windows environment (XP, Windows 2000, and up).
   
   Most developers make use of the open source development tool chain. If
   you have contributed to open source software before, you will probably
   be familiar with these tools. They include: GCC (http://gcc.gnu.org,
   GDB (www.gnu.org/software/gdb/gdb.html), autoconf
   (www.gnu.org/software/autoconf/) AND GNU make
   (www.gnu.org/software/make/make.html.
   
   Developers using this tool chain on Windows make use of MingW (see
   http://www.mingw.org/).
   
   Some developers use compilers from other software vendors with mixed
   results.
   
   Developers who regularly rebuild the source often pass the
   --enable-depend flag to configure. The result is that when you make a
   modification to a C header file, all files depend upon that file are
   also rebuilt.
   
   src/Makefile.custom can be used to set environment variables, like
   CUSTOM_COPT, that are used for every compile.
   
  1.3) What areas need work?
  
   Outstanding features are detailed in the TODO list. This is located in
   doc/TODO in the source distribution or at
   http://www.postgresql.org/docs/faqs.TODO.html.
   
   You can learn more about these features by consulting the archives,
   the SQL standards and the recommend texts (see 1.11).
   
  1.4) What do I do after choosing an item to work on?
  
   Send an email to pgsql-hackers with a proposal for what you want to do
   (assuming your contribution is not trivial). Working in isolation is
   not advisable because others might be working on the same TODO item,
   or you might have misunderstood the TODO item. In the email, discuss
   both the internal implementation method you plan to use, and any
   user-visible changes (new syntax, etc). For complex patches, it is
   important to get community feeback on your proposal before starting
   work. Failure to do so might mean your patch is rejected. If your work
   is being sponsored by a company, read this article for tips on being
   more effective.
   
   A web site is maintained for patches awaiting review,
   http://momjian.postgresql.org/cgi-bin/pgpatches, and those that are
   being kept for the next release,
   http://momjian.postgresql.org/cgi-bin/pgpatches_hold.
   
  1.5) I have developed a patch, what next?
  
   You will need to submit the patch to pgsql-patches@@postgresql.org. It
   will be reviewed by other contributors to the project and will be
   either accepted or sent back for further work. To help ensure your
   patch is reviewed and committed in a timely fashion, please try to
   make sure your submission conforms to the following guidelines:
    1. Ensure that your patch is generated against the most recent
       version of the code, which for developers is CVS HEAD. For more on
       branches in PostgreSQL, see 1.16.
    2. Try to make your patch as readable as possible by following the
       project's code-layout conventions. This makes it easier for the
       reviewer, and there's no point in trying to layout things
       differently than pgindent. Also avoid unnecessary whitespace
       changes because they just distract the reviewer, and formatting
       changes will be removed by the next run of pgindent.
    3. The patch should be generated in contextual diff format (diff -c
       and should be applicable from the root directory. If you are
       unfamiliar with this, you might find the script
       src/tools/make_diff/difforig useful. (Unified diffs are only
       preferable if the file changes are single-line changes and do not
       rely on surrounding lines.)
    4. PostgreSQL is licensed under a BSD license. By posting a patch to
       the public PostgreSQL mailling lists, you are giving the
       PostgreSQL Global Development Group the non-revokable right to
       distribute your patch under the BSD license.
    5. Confirm that your changes can pass the regression tests. If your
       changes are port specific, please list the ports you have tested
       it on.
    6. If you are adding a new feature, confirm that it has been tested
       thoroughly. Try to test the feature in all conceivable scenarios.
    7. New feature patches should also be accompanied by documentation
       patches. If you need help checking the SQL standard, see 1.17.
    8. Provide an implementation overview, preferably in code comments.
       Following the surrounding code commenting style is usually a good
       approach (also see
       http://www.ibm.com/developerworks/linux/library/l-clear-code/?ca=d
       gr-FClnxw01linuxcodetips).
    9. If it is a performance patch, please provide confirming test
       results to show the benefit of your patch. It is OK to post
       patches without this information, though the patch will not be
       applied until somebody has tested the patch and found a
       significant performance improvement.
       
   Even if you pass all of the above, the patch might still be rejected
   for other reasons. Please be prepared to listen to comments and make
   modifications.
   
   You will be notified via email when the patch is applied, and your
   name will appear in the next version of the release notes.
   
  1.6) How is a patch reviewed?
  
   Patch committers check several things before applying a patch:
     * Patch follows the SQL standard or community agreed-upon behavior
     * Style merges seamlessly into the surrounding code
     * Written as simply and efficiently as possible
     * Uses the available PostgreSQL subsystems properly
     * Contains sufficient comments
     * Contains code that works on all supported operating systems
     * Has proper documentation
     * Passes all regression tests, and if needed, adds new ones
     * Behaves as expected, even under unusual cirumstances
     * Contains no reliability risks
     * Does not overly complicate the source code
     * If performance-related, has a measureable performance benefit
     * Is of sufficient usefulness to the average PostgreSQL user
     * Follows existing PostgreSQL coding standards
       
  1.7) Where can I learn more about the code?
  
   Other than documentation in the source tree itself, you can find some
   papers/presentations discussing the code at
   http://www.postgresql.org/developer. An excellent presentation is at
   http://neilconway.org/talks/hacking/
   
  1.8) How do I download/update the current source tree?
  
   There are several ways to obtain the source tree. Occasional
   developers can just get the most recent source tree snapshot from
   ftp://ftp.postgresql.org.
   
   Regular developers might want to take advantage of anonymous access to
   our source code management system. The source tree is currently hosted
   in CVS. For details of how to obtain the source from CVS see
   http://developer.postgresql.org/docs/postgres/cvs.html.
   
  1.9) How do I test my changes?
  
   Basic system testing
   
   The easiest way to test your code is to ensure that it builds against
   the latest version of the code and that it does not generate compiler
   warnings.
   
   It is worth advised that you pass --enable-cassert to configure. This
   will turn on assertions with in the source which will often show us
   bugs because they cause data corruption of segmentation violations.
   This generally makes debugging much easier.
   
   Then, perform run time testing via psql.
   
   Regression test suite
   
   The next step is to test your changes against the existing regression
   test suite. To do this, issue "make check" in the root directory of
   the source tree. If any tests fail, investigate.
   
   If you've deliberately changed existing behavior, this change might
   cause a regression test failure but not any actual regression. If so,
   you should also patch the regression test suite.
   
   Other run time testing
   
   Some developers make use of tools such as valgrind
   (http://valgrind.kde.org) for memory testing, gprof (which comes with
   the GNU binutils suite) and oprofile
   (http://oprofile.sourceforge.net/) for profiling and other related
   tools.
   
   What about unit testing, static analysis, model checking...?
   
   There have been a number of discussions about other testing frameworks
   and some developers are exploring these ideas.
   
   Keep in mind the Makefiles do not have the proper dependencies for
   include files. You have to do a make clean and then another make. If
   you are using GCC you can use the --enable-depend option of configure
   to have the compiler compute the dependencies automatically.
   
  1.10) What tools are available for developers?
  
   First, all the files in the src/tools directory are designed for
   developers.
    RELEASE_CHANGES changes we have to make for each release
    backend         description/flowchart of the backend directories
    ccsym           find standard defines made by your compiler
     copyright       fixes copyright notices

    entab           converts spaces to tabs, used by pgindent
    find_static     finds functions that could be made static
    find_typedef    finds typedefs in the source code
    find_badmacros  finds macros that use braces incorrectly
    fsync           a script to provide information about the cost of cache
                     syncing system calls
    make_ctags      make vi 'tags' file in each directory
    make_diff       make *.orig and diffs of source
    make_etags      make emacs 'etags' files
    make_keywords   make comparison of our keywords and SQL'92
    make_mkid       make mkid ID files
    pgcvslog        used to generate a list of changes for each release
    pginclude       scripts for adding/removing include files
    pgindent        indents source files
    pgtest          a semi-automated build system
    thread          a thread testing script

   In src/include/catalog:
    unused_oids     a script which generates unused OIDs for use in system
                     catalogs
    duplicate_oids  finds duplicate OIDs in system catalog definitions

   If you point your browser at the tools/backend/index.html file, you
   will see few paragraphs describing the data flow, the backend
   components in a flow chart, and a description of the shared memory
   area. You can click on any flowchart box to see a description. If you
   then click on the directory name, you will be taken to the source
   directory, to browse the actual source code behind it. We also have
   several README files in some source directories to describe the
   function of the module. The browser will display these when you enter
   the directory also. The tools/backend directory is also contained on
   our web page under the title How PostgreSQL Processes a Query.
   
   Second, you really should have an editor that can handle tags, so you
   can tag a function call to see the function definition, and then tag
   inside that function to see an even lower-level function, and then
   back out twice to return to the original function. Most editors
   support this via tags or etags files.
   
   Third, you need to get id-utils from ftp://ftp.gnu.org/gnu/id-utils/
   
   By running tools/make_mkid, an archive of source symbols can be
   created that can be rapidly queried.
   
   Some developers make use of cscope, which can be found at
   http://cscope.sf.net/. Others use glimpse, which can be found at
   http://webglimpse.net/.
   
   tools/make_diff has tools to create patch diff files that can be
   applied to the distribution. This produces context diffs, which is our
   preferred format.
   
   Our standard format BSD style, with each level of code indented one
   tab, where each tab is four spaces. You will need to set your editor
   or file viewer to display tabs as four spaces:
    vi in ~/.exrc:
            set tabstop=4
            set sw=4
    more:
            more -x4
    less:
            less -x4

   The tools/editors directory of the latest sources contains sample
   settings that can be used with the emacs, xemacs and vim editors, that
   assist in keeping to PostgreSQL coding standards.
   
   pgindent will the format code by specifying flags to your operating
   system's utility indent. This article describes the value of a
   consistent coding style.
   
   pgindent is run on all source files just before each beta test period.
   It auto-formats all source files to make them consistent. Comment
   blocks that need specific line breaks should be formatted as block
   comments, where the comment starts as /*------. These comments will
   not be reformatted in any way.
   
   pginclude contains scripts used to add needed #include's to include
   files, and removed unneeded #include's.
   
   When adding system types, you will need to assign oids to them. There
   is also a script called unused_oids in pgsql/src/include/catalog that
   shows the unused oids.
   
  1.11) What books are good for developers?
  
   There are five good books:
     * An Introduction to Database Systems, by C.J. Date, Addison, Wesley
     * A Guide to the SQL Standard, by C.J. Date, et. al, Addison, Wesley
     * Fundamentals of Database Systems, by Elmasri and Navathe
     * Transaction Processing, by Jim Gray, Morgan, Kaufmann
     * Transactional Information Systems by Gerhard Weikum, Kaufmann
       
  1.12) What is configure all about?
  
   The files configure and configure.in are part of the GNU autoconf
   package. Configure allows us to test for various capabilities of the
   OS, and to set variables that can then be tested in C programs and
   Makefiles. Autoconf is installed on the PostgreSQL main server. To add
   options to configure, edit configure.in, and then run autoconf to
   generate configure.
   
   When configure is run by the user, it tests various OS capabilities,
   stores those in config.status and config.cache, and modifies a list of
   *.in files. For example, if there exists a Makefile.in, configure
   generates a Makefile that contains substitutions for all @@var@@
   parameters found by configure.
   
   When you need to edit files, make sure you don't waste time modifying
   files generated by configure. Edit the *.in file, and re-run configure
   to recreate the needed file. If you run make distclean from the
   top-level source directory, all files derived by configure are
   removed, so you see only the file contained in the source
   distribution.
   
  1.13) How do I add a new port?
  
   There are a variety of places that need to be modified to add a new
   port. First, start in the src/template directory. Add an appropriate
   entry for your OS. Also, use src/config.guess to add your OS to
   src/template/.similar. You shouldn't match the OS version exactly. The
   configure test will look for an exact OS version number, and if not
   found, find a match without version number. Edit src/configure.in to
   add your new OS. (See configure item above.) You will need to run
   autoconf, or patch src/configure too.
   
   Then, check src/include/port and add your new OS file, with
   appropriate values. Hopefully, there is already locking code in
   src/include/storage/s_lock.h for your CPU. There is also a
   src/makefiles directory for port-specific Makefile handling. There is
   a backend/port directory if you need special files for your OS.
   
  1.14) Why don't you use threads, raw devices, async-I/O, <insert your
  favorite wizz-bang feature here>?
  
   There is always a temptation to use the newest operating system
   features as soon as they arrive. We resist that temptation.
   
   First, we support 15+ operating systems, so any new feature has to be
   well established before we will consider it. Second, most new
   wizz-bang features don't provide dramatic improvements. Third, they
   usually have some downside, such as decreased reliability or
   additional code required. Therefore, we don't rush to use new features
   but rather wait for the feature to be established, then ask for
   testing to show that a measurable improvement is possible.
   
   As an example, threads are not currently used in the backend code
   because:
     * Historically, threads were unsupported and buggy.
     * An error in one backend can corrupt other backends.
     * Speed improvements using threads are small compared to the
       remaining backend startup time.
     * The backend code would be more complex.
       
   So, we are not ignorant of new features. It is just that we are
   cautious about their adoption. The TODO list often contains links to
   discussions showing our reasoning in these areas.
   
  1.15) How are RPMs packaged?
  
   This was written by Lamar Owen and Devrim Gündüz:
   
   2006-10-16
   
   As to how the RPMs are built -- to answer that question sanely
   requires us to know how much experience you have with the whole RPM
   paradigm. 'How is the RPM built?' is a multifaceted question. The
   obvious simple answer is that we maintain:
    1. A set of patches to make certain portions of the source tree
       'behave' in the different environment of the RPMset;
    2. The initscript;
    3. Any other ancillary scripts and files;
    4. A README.rpm-dist document that tries to adequately document both
       the differences between the RPM build and the WHY of the
       differences, as well as useful RPM environment operations (like,
       using syslog, upgrading, getting postmaster to start at OS boot,
       etc);
    5. The spec file that throws it all together. This is not a trivial
       undertaking in a package of this size.
       
   PGDG RPM Maintainer builds the SRPM and announces the SRPM to the
   pgsqlrpms-hackers list. This is a list where package builders are
   subscribed. Then, the builders download the SRPM and rebuild it on
   their machines.
   
   We try to build on as many different canonical distributions as we
   can. Currently we are able to build on Red Hat Linux 9, RHEL 3 and
   above, and all Fedora Core Linux releases.
   
   To test the binaries, we install them on our local machines and run
   regression tests. If the package builders uses postgres user to build
   the rpms, then it is possible to run regression tests during RPM
   builds.
   
   Once the build passes these tests, the binary RPMs are sent back to
   PGDG RPM Maintainer and they are pushed to main FTP site, followed by
   a release announcement to pgsqlrpms-* lists, pgsql-general and
   pgsql-announce lists.
   
   You will notice we said 'canonical' distributions above. That simply
   means that the machine is as stock 'out of the box' as practical --
   that is, everything (except select few programs) on these boxen are
   installed by RPM; only official Red Hat released RPMs are used (except
   in unusual circumstances involving software that will not alter the
   build -- for example, installing a newer non-RedHat version of the Dia
   diagramming package is OK -- installing Python 2.1 on the box that has
   Python 1.5.2 installed is not, as that alters the PostgreSQL build).
   The RPM as uploaded is built to as close to out-of-the-box pristine as
   is possible. Only the standard released 'official to that release'
   compiler is used -- and only the standard official kernel is used as
   well.
   
   PGDG RPM Building Project does not build RPMs for Mandrake .
   
   We usually have only one SRPM for all platforms. This is because of
   our limited resources. However, on some cases, we may distribute
   different SRPMs for different platforms, depending on possible
   compilation problems, especially on older distros.
   
   Please note that this is a volunteered job -- We are doing our best to
   keep packages up to date. We, at least, provide SRPMs for all
   platforms. For example, if you do not find a RHEL 4 x86_64 RPM in our
   FTP site, it means that we do not have a RHEL 4 x86_64 server around.
   If you have one and want to help us, please do not hesitate to build
   rpms and send to us :-)
   http://pgfoundry.org/docman/view.php/1000048/98/PostgreSQL-RPM-Install
   ation-PGDG.pdf has some information about building binary RPMs using
   an SRPM.
   
   PGDG RPM Building Project is a hosted on pgFoundry :
   http://pgfoundry.org/projects/pgsqlrpms. We are an open community,
   except one point : Our pgsqlrpms-hackers list is open to package
   builders only. Still, its archives are visible to public. We use a CVS
   server to save the work we have done so far. This includes spec files
   and patches; as well as documents.
   
   As to why all these files aren't part of the source tree, well, unless
   there was a large cry for it to happen, we don't believe it should.
   
  1.16) How are CVS branches managed?
  
   This was written by Tom Lane:
   
   2001-05-07
   
   If you just do basic "cvs checkout", "cvs update", "cvs commit", then
   you'll always be dealing with the HEAD version of the files in CVS.
   That's what you want for development, but if you need to patch past
   stable releases then you have to be able to access and update the
   "branch" portions of our CVS repository. We normally fork off a branch
   for a stable release just before starting the development cycle for
   the next release.
   
   The first thing you have to know is the branch name for the branch you
   are interested in getting at. To do this, look at some long-lived
   file, say the top-level HISTORY file, with "cvs status -v" to see what
   the branch names are. (Thanks to Ian Lance Taylor for pointing out
   that this is the easiest way to do it.) Typical branch names are:
    REL7_1_STABLE
    REL7_0_PATCHES
    REL6_5_PATCHES

   OK, so how do you do work on a branch? By far the best way is to
   create a separate checkout tree for the branch and do your work in
   that. Not only is that the easiest way to deal with CVS, but you
   really need to have the whole past tree available anyway to test your
   work. (And you *better* test your work. Never forget that dot-releases
   tend to go out with very little beta testing --- so whenever you
   commit an update to a stable branch, you'd better be doubly sure that
   it's correct.)
   
   Normally, to checkout the head branch, you just cd to the place you
   want to contain the toplevel "pgsql" directory and say
    cvs ... checkout pgsql

   To get a past branch, you cd to wherever you want it and say
    cvs ... checkout -r BRANCHNAME pgsql

   For example, just a couple days ago I did
    mkdir ~postgres/REL7_1
    cd ~postgres/REL7_1
    cvs ... checkout -r REL7_1_STABLE pgsql

   and now I have a maintenance copy of 7.1.*.
   
   When you've done a checkout in this way, the branch name is "sticky":
   CVS automatically knows that this directory tree is for the branch,
   and whenever you do "cvs update" or "cvs commit" in this tree, you'll
   fetch or store the latest version in the branch, not the head version.
   Easy as can be.
   
   So, if you have a patch that needs to apply to both the head and a
   recent stable branch, you have to make the edits and do the commit
   twice, once in your development tree and once in your stable branch
   tree. This is kind of a pain, which is why we don't normally fork the
   tree right away after a major release --- we wait for a dot-release or
   two, so that we won't have to double-patch the first wave of fixes.
   
  1.17) Where can I get a copy of the SQL standards?
  
   There are three versions of the SQL standard: SQL-92, SQL:1999, and
   SQL:2003. They are endorsed by ANSI and ISO. Draft versions can be
   downloaded from:
     * SQL-92 http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
     * SQL:1999
       http://www.cse.iitb.ac.in/dbms/Data/Papers-Other/SQL1999/ansi-iso-
       9075-2-1999.pdf
     * SQL:2003 http://www.wiscorp.com/sql_2003_standard.zip
       
   Some SQL standards web pages are:
     * http://troels.arvin.dk/db/rdbms/links/#standards
     * http://www.wiscorp.com/SQLStandards.html
     * http://www.contrib.andrew.cmu.edu/~shadow/sql.html#syntax (SQL-92)
     * http://dbs.uni-leipzig.de/en/lokal/standards.pdf (paper)
       
  1.18) Where can I get technical assistance?
  
   Many technical questions held by those new to the code have been
   answered on the pgsql-hackers mailing list - the archives of which can
   be found at http://archives.postgresql.org/pgsql-hackers/.
   
   If you cannot find discussion or your particular question, feel free
   to put it to the list.
   
   Major contributors also answer technical questions, including
   questions about development of new features, on IRC at
   irc.freenode.net in the #postgresql channel.
   
  1.19) How do I get involved in PostgreSQL web site development?
  
   PostgreSQL website development is discussed on the
   pgsql-www@@postgresql.org mailing list. The is a project page where the
   source code is available at http://pgfoundry.org/projects/pgweb.
   
  1.20) Why haven't you replaced CVS with SVN, Git, Monotone, VSS, <insert your
  favorite SCMS here>?
  
   Currently the core developers see no SCMS that will provide enough
   benefit to outwiegh the pain involved in moving to a new SCMS. Typical
   problems that must be addressed by any new SCMS include:
     * Run natively on all of our supported platforms.
     * Integrate into the Buildfarm.
     * Import our entire CVS Repository while preserving complete
       history.
     * Allow for anonymous checkouts.
       
   Currently there is no intention for switching to a new SCMS until at
   least the end of the 8.4 development cycle sometime in late 2008. For
   more information please refer to the mailing list archives.
   
Technical Questions

  2.1) How do I efficiently access information in tables from the backend code?
  
   You first need to find the tuples(rows) you are interested in. There
   are two ways. First, SearchSysCache() and related functions allow you
   to query the system catalogs. This is the preferred way to access
   system tables, because the first call to the cache loads the needed
   rows, and future requests can return the results without accessing the
   base table. The caches use system table indexes to look up tuples. A
   list of available caches is located in
   src/backend/utils/cache/syscache.c.
   src/backend/utils/cache/lsyscache.c contains many column-specific
   cache lookup functions.
   
   The rows returned are cache-owned versions of the heap rows.
   Therefore, you must not modify or delete the tuple returned by
   SearchSysCache(). What you should do is release it with
   ReleaseSysCache() when you are done using it; this informs the cache
   that it can discard that tuple if necessary. If you neglect to call
   ReleaseSysCache(), then the cache entry will remain locked in the
   cache until end of transaction, which is tolerable but not very
   desirable.
   
   If you can't use the system cache, you will need to retrieve the data
   directly from the heap table, using the buffer cache that is shared by
   all backends. The backend automatically takes care of loading the rows
   into the buffer cache.
   
   Open the table with heap_open(). You can then start a table scan with
   heap_beginscan(), then use heap_getnext() and continue as long as
   HeapTupleIsValid() returns true. Then do a heap_endscan(). Keys can be
   assigned to the scan. No indexes are used, so all rows are going to be
   compared to the keys, and only the valid rows returned.
   
   You can also use heap_fetch() to fetch rows by block number/offset.
   While scans automatically lock/unlock rows from the buffer cache, with
   heap_fetch(), you must pass a Buffer pointer, and ReleaseBuffer() it
   when completed.
   
   Once you have the row, you can get data that is common to all tuples,
   like t_self and t_oid, by merely accessing the HeapTuple structure
   entries. If you need a table-specific column, you should take the
   HeapTuple pointer, and use the GETSTRUCT() macro to access the
   table-specific start of the tuple. You then cast the pointer as a
   Form_pg_proc pointer if you are accessing the pg_proc table, or
   Form_pg_type if you are accessing pg_type. You can then access the
   columns by using a structure pointer:
((Form_pg_class) GETSTRUCT(tuple))->relnatts

   You must not directly change live tuples in this way. The best way is
   to use heap_modifytuple() and pass it your original tuple, and the
   values you want changed. It returns a palloc'ed tuple, which you pass
   to heap_replace(). You can delete tuples by passing the tuple's t_self
   to heap_destroy(). You use t_self for heap_update() too. Remember,
   tuples can be either system cache copies, which might go away after
   you call ReleaseSysCache(), or read directly from disk buffers, which
   go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in
   the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
   pfree() when finished.
   
  2.2) Why are table, column, type, function, view names sometimes referenced
  as Name or NameData, and sometimes as char *?
  
   Table, column, type, function, and view names are stored in system
   tables in columns of type Name. Name is a fixed-length,
   null-terminated type of NAMEDATALEN bytes. (The default value for
   NAMEDATALEN is 64 bytes.)
typedef struct nameData
    {
        char        data[NAMEDATALEN];
    } NameData;
    typedef NameData *Name;

   Table, column, type, function, and view names that come into the
   backend via user queries are stored as variable-length,
   null-terminated character strings.
   
   Many functions are called with both types of names, ie. heap_open().
   Because the Name type is null-terminated, it is safe to pass it to a
   function expecting a char *. Because there are many cases where
   on-disk names(Name) are compared to user-supplied names(char *), there
   are many cases where Name and char * are used interchangeably.
   
  2.3) Why do we use Node and List to make data structures?
  
   We do this because this allows a consistent way to pass data inside
   the backend in a flexible way. Every node has a NodeTag which
   specifies what type of data is inside the Node. Lists are groups of
   Nodes chained together as a forward-linked list.
   
   Here are some of the List manipulation commands:
   
   lfirst(i), lfirst_int(i), lfirst_oid(i)
          return the data (a pointer, integer or OID respectively) of
          list cell i.
          
   lnext(i)
          return the next list cell after i.
          
   foreach(i, list)
          loop through list, assigning each list cell to i. It is
          important to note that i is a ListCell *, not the data in the
          List element. You need to use lfirst(i) to get at the data.
          Here is a typical code snippet that loops through a List
          containing Var *'s and processes each one:
          

    List        *list;
    ListCell    *i;

    foreach(i, list)
    {
        Var *var = lfirst(i);

        /* process var here */
    }

   lcons(node, list)
          add node to the front of list, or create a new list with node
          if list is NIL.
          
   lappend(list, node)
          add node to the end of list.
          
   list_concat(list1, list2)
          Concatenate list2 on to the end of list1.
          
   list_length(list)
          return the length of the list.
          
   list_nth(list, i)
          return the i'th element in list, counting from zero.
          
   lcons_int, ...
          There are integer versions of these: lcons_int, lappend_int,
          etc. Also versions for OID lists: lcons_oid, lappend_oid, etc.
          
   You can print nodes easily inside gdb. First, to disable output
   truncation when you use the gdb print command:
(gdb) set print elements 0

   Instead of printing values in gdb format, you can use the next two
   commands to print out List, Node, and structure contents in a verbose
   format that is easier to understand. List's are unrolled into nodes,
   and nodes are printed in detail. The first prints in a short format,
   and the second in a long format:
(gdb) call print(any_pointer)
    (gdb) call pprint(any_pointer)

   The output appears in the server log file, or on your screen if you
   are running a backend directly without a postmaster.
   
  2.4) I just added a field to a structure. What else should I do?
  
   The structures passed around in the parser, rewriter, optimizer, and
   executor require quite a bit of support. Most structures have support
   routines in src/backend/nodes used to create, copy, read, and output
   those structures (in particular, the files copyfuncs.c and
   equalfuncs.c. Make sure you add support for your new field to these
   files. Find any other places the structure might need code for your
   new field. mkid is helpful with this (see 1.10).
   
  2.5) Why do we use palloc() and pfree() to allocate memory?
  
   palloc() and pfree() are used in place of malloc() and free() because
   we find it easier to automatically free all memory allocated when a
   query completes. This assures us that all memory that was allocated
   gets freed even if we have lost track of where we allocated it. There
   are special non-query contexts that memory can be allocated in. These
   affect when the allocated memory is freed by the backend.
   
  2.6) What is ereport()?
  
   ereport() is used to send messages to the front-end, and optionally
   terminate the current query being processed. The first parameter is an
   ereport level of DEBUG (levels 1-5), LOG, INFO, NOTICE, ERROR, FATAL,
   or PANIC. NOTICE prints on the user's terminal and to the server logs.
   INFO prints only to the user's terminal and LOG prints only to the
   server logs. (These can be changed from postgresql.conf.) ERROR prints
   in both places, and terminates the current query, never returning from
   the call. FATAL terminates the backend process. The remaining
   parameters of ereport are a printf-style set of parameters to print.
   
   ereport(ERROR) frees most memory and open file descriptors so you
   don't need to clean these up before the call.
   
  2.7) What is CommandCounterIncrement()?
  
   Normally, transactions can not see the rows they modify. This allows
   UPDATE foo SET x = x + 1 to work correctly.
   
   However, there are cases where a transactions needs to see rows
   affected in previous parts of the transaction. This is accomplished
   using a Command Counter. Incrementing the counter allows transactions
   to be broken into pieces so each piece can see rows modified by
   previous pieces. CommandCounterIncrement() increments the Command
   Counter, creating a new part of the transaction.
   
  2.8) What debugging features are available?
  
   First, try running configure with the --enable-cassert option, many
   assert()s monitor the progress of the backend and halt the program
   when something unexpected occurs.
   
   The postgres server has a -d option that allows even more detailed
   information to be reported. The -d option takes a number that
   specifies the debug level. Be warned that high debug level values
   generate large log files.
   
   If the postmaster is not running, you can actually run the postgres
   backend from the command line, and type your SQL statement directly.
   This is recommended only for debugging purposes. If you have compiled
   with debugging symbols, you can use a debugger to see what is
   happening. Because the backend was not started from postmaster, it is
   not running in an identical environment and locking/backend
   interaction problems might not be duplicated.
   
   If the postmaster is running, start psql in one window, then find the
   PID of the postgres process used by psql using SELECT
   pg_backend_pid(). Use a debugger to attach to the postgres PID. You
   can set breakpoints in the debugger and issue queries from the other.
   If you are looking to find the location that is generating an error or
   log message, set a breakpoint at errfinish. psql. If you are debugging
   postgres startup, you can set PGOPTIONS="-W n", then start psql. This
   will cause startup to delay for n seconds so you can attach to the
   process with the debugger, set any breakpoints, and continue through
   the startup sequence.
   
   You can also compile with profiling to see what functions are taking
   execution time. The backend profile files will be deposited in the
   pgsql/data directory. The client profile file will be put in the
   client's current directory. Linux requires a compile with
   -DLINUX_PROFILE for proper profiling.
@


1.146.2.1
log
@Replace developer FAQ with a reference to the wiki, which is where
it now lives (per discussion). Leave the other FAQs alone for now.
@
text
@a0 1
The developer FAQ can be found on the PostgreSQL wiki:
d2 838
a839 1
  http://wiki.postgresql.org/wiki/Development_information
@


1.145
log
@Remove second-in-paragraph usage of "Postgres" in FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Fri Oct 26 15:08:39 EDT 2007
d588 1
a588 3
   source code is available at
   http://gborg.postgresql.org/project/pgweb/projdisplay.php , the code
   for the next version of the website is under the "portal" module.
@


1.144
log
@Clarify user of "postmaster" vs. "server" in FAQs.

Brendan Jurd
@
text
@d4 1
a4 1
   Last updated: Wed Sep 26 16:38:09 EDT 2007
d140 3
a142 3
       the public Postgres mailling lists, you are giving the PostgreSQL
       Global Development Group the non-revokable right to distribute
       your patch under the BSD license.
d183 2
a184 2
     * Is of sufficient usefulness to the average Postgres user
     * Follows existing Postgres coding standards
d431 1
a431 1
       using syslog, upgrading, getting the server to start at OS boot,
d758 2
a759 2
   The output appears in the server log file, or on your screen if
   you are running a backend directly.
d785 6
a790 7
   or PANIC. NOTICE prints on the user's terminal and to the server
   logs. INFO prints only to the user's terminal and LOG prints only to
   the server logs. (These can be changed from postgresql.conf.) ERROR
   prints in both places, and terminates the current query, never
   returning from the call. FATAL terminates the backend process. The
   remaining parameters of ereport are a printf-style set of parameters
   to print.
@


1.143
log
@Rename "PostgreSQL" to "Postgres" in 3 places.
@
text
@d431 1
a431 1
       using syslog, upgrading, getting postmaster to start at OS boot,
d758 2
a759 2
   The output appears in the postmaster log file, or on your screen if
   you are running a backend directly without a postmaster.
d785 1
a785 1
   or PANIC. NOTICE prints on the user's terminal and the postmaster
d814 1
a814 1
   The postmaster has a -d option that allows even more detailed
@


1.142
log
@Typo fix from Brendan Jurd.
@
text
@d4 1
a4 1
   Last updated: Sun Sep 23 14:06:36 EDT 2007
d140 3
a142 3
       the public PostgreSQL mailling lists, you are giving the
       PostgreSQL Global Development Group the non-revokable right to
       distribute your patch under the BSD license.
d183 2
a184 2
     * Is of sufficient usefulness to the average PostgreSQL user
     * Follows existing PostgreSQL coding standards
@


1.141
log
@Fix typo in FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Wed Aug 22 20:10:01 EDT 2007
d223 1
a223 1
   the source tree. If any tests failure, investigate.
@


1.140
log
@Add book to FAQ_DEV:

Transactional Information Systems by Gerhard Weikum, Kaufmann
@
text
@d4 1
a4 1
   Last updated: Wed Aug 22 20:09:21 EDT 2007
d347 1
a347 1
     * Transactional Information Systems by by Gerhard Weikum, Kaufmann
@


1.139
log
@Remove http://www.benchmarkresources.com, no longer resolves to a
meaningful site.
@
text
@d4 1
a4 1
   Last updated: Tue Jul 17 01:03:37 EDT 2007
d342 7
a348 5
   I have four good books, An Introduction to Database Systems, by C.J.
   Date, Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et.
   al, Addison, Wesley, Fundamentals of Database Systems, by Elmasri and
   Navathe, and Transaction Processing, by Jim Gray, Morgan, Kaufmann
   
@


1.138
log
@Wording improvement.
@
text
@d4 1
a4 1
   Last updated: Fri Jun 1 00:11:39 EDT 2007
a346 3
   There is also a database performance site, with a handbook on-line
   written by Jim Gray at http://www.benchmarkresources.com..
   
@


1.137
log
@Update FAQ_DEV URL to output for text format.
@
text
@d4 1
a4 1
   Last updated: Fri Jun 1 00:05:22 EDT 2007
d152 1
a152 1
       approach (also see this
@


1.136
log
@Add URL for code comments to developer's FAQ:

	http://www.ibm.com/developerworks/linux/library/l-clear-code/?ca=dgr-FClnxw01linuxcodetips
@
text
@d4 1
a4 1
   Last updated: Thu May 31 20:28:04 EDT 2007
d152 3
a154 1
       approach (also see this article).
@


1.135
log
@Wording update to FAQ_DEV..
@
text
@d4 1
a4 1
   Last updated: Sat May 5 10:33:44 EDT 2007
d152 1
a152 1
       approach.
@


1.134
log
@Add note to FAQ_DEV that regression tests might need to be added.
@
text
@d4 1
a4 1
   Last updated: Sat May 5 10:30:33 EDT 2007
d176 1
a176 1
     * Passes all regression tests, and if needed, includes new ones
@


1.133
log
@In developer's FAQ, update list API, from Tom Lane.
@
text
@d4 1
a4 1
   Last updated: Sat May 5 06:20:41 EDT 2007
d176 1
a176 1
     * Passes all regression tests
@


1.132
log
@Add FAQ item about how patches are reviewed.
@
text
@d4 1
a4 1
   Last updated: Sat May 5 00:09:15 EDT 2007
d701 2
a702 2
          return the data (a point, integer and OID respectively) at list
          element i.
d705 1
a705 1
          return the next list element after i.
d708 5
a712 5
          loop through list, assigning each list element to i. It is
          important to note that i is a List *, not the data in the List
          element. You need to use lfirst(i) to get at the data. Here is
          a typical code snippet that loops through a List containing Var
          *'s and processes each one:
d714 2
a715 1
 List                *list;
d730 1
a730 1
          add node to the end of list. This is more expensive that lcons.
d732 2
a733 2
   nconc(list1, list2)
          Concat list2 on to the end of list1.
d735 1
a735 1
   length(list)
d738 2
a739 2
   nth(i, list)
          return the i'th element in list.
d741 3
a743 3
   lconsi, ...
          There are integer versions of these: lconsi, lappendi, etc.
          Also versions for OID lists: lconso, lappendo, etc.
d762 1
a762 1
   The structures passing around from the parser, rewrite, optimizer, and
@


1.131
log
@Remove last line of patch license, per Zeugswetter Andreas:

"If the patch is not BSD-licensed, it will be rejected."
@
text
@d4 1
a4 1
   Last updated: Mon Mar 19 12:52:30 EDT 2007
d18 10
a27 9
   1.5) I've developed a patch, what next?
   1.6) Where can I learn more about the code?
   1.7) How do I download/update the current source tree?
   1.8) How do I test my changes?
   1.9) What tools are available for developers?
   1.10) What books are good for developers?
   1.11) What is configure all about?
   1.12) How do I add a new port?
   1.13) Why don't you use threads, raw devices, async-I/O, <insert your
d29 6
a34 6
   1.14) How are RPM's packaged?
   1.15) How are CVS branches handled?
   1.16) Where can I get a copy of the SQL standards?
   1.17) Where can I get technical assistance?
   1.18) How do I get involved in PostgreSQL web site development?
   1.19) Why haven't you replaced CVS with SVN, Git, Monotone, VSS,
d55 1
a55 1
   Download the code and have a look around. See 1.7.
d97 1
a97 1
   the SQL standards and the recommend texts (see 1.10).
d117 1
a117 1
  1.5) I've developed a patch, what next?
d126 1
a126 1
       branches in PostgreSQL, see 1.15.
d149 1
a149 1
       patches. If you need help checking the SQL standard, see 1.16.
d166 19
a184 1
  1.6) Where can I learn more about the code?
d191 1
a191 1
  1.7) How do I download/update the current source tree?
d202 1
a202 1
  1.8) How do I test my changes?
d245 1
a245 1
  1.9) What tools are available for developers?
d338 1
a338 1
  1.10) What books are good for developers?
d348 1
a348 1
  1.11) What is configure all about?
d370 1
a370 1
  1.12) How do I add a new port?
d387 1
a387 1
  1.13) Why don't you use threads, raw devices, async-I/O, <insert your
d413 1
a413 1
  1.14) How are RPMs packaged?
d494 1
a494 1
  1.15) How are CVS branches managed?
d553 1
a553 1
  1.16) Where can I get a copy of the SQL standards?
d570 1
a570 1
  1.17) Where can I get technical assistance?
d583 1
a583 1
  1.18) How do I get involved in PostgreSQL web site development?
d591 1
a591 1
  1.19) Why haven't you replaced CVS with SVN, Git, Monotone, VSS, <insert your
d767 1
a767 1
   new field. mkid is helpful with this (see 1.9).
@


1.130
log
@Remove timeline for 8.3 release, now on web site.
@
text
@d4 1
a4 1
   Last updated: Mon Mar 5 13:03:51 EST 2007
d141 1
a141 2
       distribute your patch under the BSD license. If the patch is not
       BSD-licensed, it will be rejected.
@


1.129
log
@Update license wording in FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Sat Mar 3 11:12:29 EST 2007
d33 1
a33 2
   1.19) What is the timeline for the next major PostgreSQL release?
   1.20) Why haven't you replaced CVS with SVN, Git, Monotone, VSS,
d573 1
a573 14
  1.19) What is the timeline for the next major PostgreSQL release?
  
   The development schedule for the 8.3 release is:
     * March 1, 2007 - Initial community review of all major feature
       patches
     * April 1, 2007 - Feature freeze, all patches must be submitted for
       review and application
     * mid-May, 2007 - All patches applied, beta testing begins
     * July, 2007 - Release of 8.3.0
       
   Patches that appear after appropriate dates are typically not applied
   but held for the next major release.
   
  1.20) Why haven't you replaced CVS with SVN, Git, Monotone, VSS, <insert your
@


1.128
log
@HTML markup fix.
@
text
@d4 1
a4 1
   Last updated: Fri Mar 2 16:03:49 EST 2007
d142 2
a143 4
       distribute your patch under the BSD license. If you use code that
       is available under a BSD-compatible license (eg. public domain),
       please note that in your email submission. If the license is not
       BSD-compatible (e.g. GPL), please do not post the patch.
@


1.127
log
@Fix HTML markup.
@
text
@d4 1
a4 1
   Last updated: Fri Mar 2 16:03:04 EST 2007
@


1.126
log
@in FAQ_DEV, mention we don't want non-BSD-compatible licensed patches.
@
text
@d4 1
a4 1
   Last updated: Fri Mar 2 12:51:32 EST 2007
d582 2
a583 2
       review and applicationmid-May, 2007 - All patches applied, beta
       testing begins
@


1.125
log
@Add language about rights given by posting a patch:

    <li>PostgreSQL is licensed under a BSD license.  By posting a patch
    to the public PostgreSQL mailling lists, you are giving the PostgreSQL
    Global Development Group the non-revokable right to distribute your
    patch under the BSD license.  If you use code that is available under
    some other license that is BSD compatible (eg. public domain), please
    note that in your email submission.</li>
@
text
@d4 1
a4 1
   Last updated: Wed Feb 28 12:27:44 EST 2007
d143 3
a145 2
       is available under some other license that is BSD compatible (eg.
       public domain), please note that in your email submission.
@


1.124
log
@Update release timeline to use unnumber lists HTML.
@
text
@d4 1
a4 1
   Last updated: Tue Feb 27 18:12:31 EST 2007
d139 6
a144 4
    4. PostgreSQL is licensed under a BSD license, so any submissions
       must conform to the BSD license to be included. If you use code
       that is available under some other license that is BSD compatible
       (eg. public domain) please note that code in your email submission
d148 5
a152 1
    6. Provide an implementation overview, preferably in code comments.
a154 4
    7. New feature patches should also be accompanied by documentation
       patches. If you need help checking the SQL standard, see 1.16.
    8. If you are adding a new feature, confirm that it has been tested
       thoroughly. Try to test the feature in all conceivable scenarios.
@


1.123
log
@Update DEV FAQ for CVS/SVN issue.

Robert Treat
@
text
@d4 1
a4 1
   Last updated: Tue Feb 27 16:06:41 EST 2007
d576 7
a582 15
   
          March 1, 2007
          
   Initial community review of all major feature patches
          April 1, 2007
          
   Feature freeze, all patches must be submitted for review and
          application
          mid-May, 2007
          
   All patches applied, beta testing begins
          July, 2007
          
   Release of 8.3.0
          
@


1.122
log
@Add FAQ text about Makefile.custom:

    <P><I>src/Makefile.custom</I> can be used to set environment variables,
    like <I>CUSTOM_COPT</I>, that are used for every compile.
@
text
@d4 1
a4 1
   Last updated: Mon Feb 19 18:44:29 EST 2007
d34 2
d573 37
a843 21
   
  2.9) What is the timeline for the next major PostgreSQL release?
  
   The development schedule for the 8.3 release is:
   
          March 1, 2007
          
   Initial community review of all major feature patches
          April 1, 2007
          
   Feature freeze, all patches must be submitted for review and
          application
          mid-May, 2007
          
   All patches applied, beta testing begins
          July, 2007
          
   Release of 8.3.0
          
   Patches that appear after appropriate dates are typically not applied
   but held for the next major release.
@


1.121
log
@Fix tab to space mention in FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Thu Jan 4 16:00:00 EST 2007
d80 1
a80 1
   Developers who are regularly rebuilding the source often pass the
d85 3
@


1.120
log
@Add a link to the developer's FAQ for my article about how companies can
work effectively with open source communities.
@
text
@d4 1
a4 1
   Last updated: Fri Dec 22 17:41:41 EST 2006
d231 1
a231 1
    entab           converts tabs to spaces, used by pgindent
@


1.119
log
@8.3 release schedule is year 2007, not 2006.
@
text
@d4 1
a4 1
   Last updated: Wed Dec 20 11:21:55 EST 2006
d103 3
a105 1
   work. Failure to do so might mean your patch is rejected.
@


1.118
log
@Add timeline for next release to developer's FAQ.
@
text
@d4 1
a4 1
   Last updated: Tue Dec 19 17:37:24 EST 2006
d805 1
a805 1
          March 1, 2006
d808 1
a808 1
          April 1, 2006
d812 1
a812 1
          mid-May, 2006
d815 1
a815 1
          July, 2006
@


1.117
log
@Fix URL for patch hold queue.
@
text
@d4 1
a4 1
   Last updated: Mon Nov 13 23:18:46 EST 2006
d33 1
d800 21
@


1.117.2.1
log
@Stamp release 8.2.1.  Update FAQs.
@
text
@d4 1
a4 1
   Last updated: Thu Jan 4 16:00:00 EST 2007
a32 1
   1.19) What is the timeline for the next major PostgreSQL release?
d102 1
a102 3
   work. Failure to do so might mean your patch is rejected. If your work
   is being sponsored by a company, read this article for tips on being
   more effective.
d228 1
a228 1
    entab           converts spaces to tabs, used by pgindent
a798 21
   
  2.9) What is the timeline for the next major PostgreSQL release?
  
   The development schedule for the 8.3 release is:
   
          March 1, 2007
          
   Initial community review of all major feature patches
          April 1, 2007
          
   Feature freeze, all patches must be submitted for review and
          application
          mid-May, 2007
          
   All patches applied, beta testing begins
          July, 2007
          
   Release of 8.3.0
          
   Patches that appear after appropriate dates are typically not applied
   but held for the next major release.
@


1.117.2.2
log
@Stamp releases 8.2.4, 8.1.9, 8.0.13, 7.4.17, 7.3.19.
@
text
@d4 1
a4 1
   Last updated: Mon Mar 19 12:52:30 EDT 2007
d33 1
a33 2
   1.19) Why haven't you replaced CVS with SVN, Git, Monotone, VSS,
   <insert your favorite SCM system here>?
d80 1
a80 1
   Developers who regularly rebuild the source often pass the
a84 3
   src/Makefile.custom can be used to set environment variables, like
   CUSTOM_COPT, that are used for every compile.
   
d134 4
a137 4
    4. PostgreSQL is licensed under a BSD license. By posting a patch to
       the public PostgreSQL mailling lists, you are giving the
       PostgreSQL Global Development Group the non-revokable right to
       distribute your patch under the BSD license.
d141 3
a143 2
    6. If you are adding a new feature, confirm that it has been tested
       thoroughly. Try to test the feature in all conceivable scenarios.
d146 2
a147 3
    8. Provide an implementation overview, preferably in code comments.
       Following the surrounding code commenting style is usually a good
       approach.
a567 16
  1.19) Why haven't you replaced CVS with SVN, Git, Monotone, VSS, <insert your
  favorite SCMS here>?
  
   Currently the core developers see no SCMS that will provide enough
   benefit to outwiegh the pain involved in moving to a new SCMS. Typical
   problems that must be addressed by any new SCMS include:
     * Run natively on all of our supported platforms.
     * Integrate into the Buildfarm.
     * Import our entire CVS Repository while preserving complete
       history.
     * Allow for anonymous checkouts.
       
   Currently there is no intention for switching to a new SCMS until at
   least the end of the 8.4 development cycle sometime in late 2008. For
   more information please refer to the mailing list archives.
   
d802 21
@


1.117.2.3
log
@Stamp releases 8.2.5, 8.1.10, 8.0.14, 7.4.18, 7.3.20.

Update FAQs for 8.2.5.
@
text
@d4 1
a4 1
   Last updated: Wed Aug 22 20:10:01 EDT 2007
d18 9
a26 10
   1.5) I have developed a patch, what next?
   1.6) How is a patch reviewed?
   1.7) Where can I learn more about the code?
   1.8) How do I download/update the current source tree?
   1.9) How do I test my changes?
   1.10) What tools are available for developers?
   1.11) What books are good for developers?
   1.12) What is configure all about?
   1.13) How do I add a new port?
   1.14) Why don't you use threads, raw devices, async-I/O, <insert your
d28 6
a33 6
   1.15) How are RPM's packaged?
   1.16) How are CVS branches handled?
   1.17) Where can I get a copy of the SQL standards?
   1.18) Where can I get technical assistance?
   1.19) How do I get involved in PostgreSQL web site development?
   1.20) Why haven't you replaced CVS with SVN, Git, Monotone, VSS,
d54 1
a54 1
   Download the code and have a look around. See 1.8.
d96 1
a96 1
   the SQL standards and the recommend texts (see 1.11).
d116 1
a116 1
  1.5) I have developed a patch, what next?
d125 1
a125 1
       branches in PostgreSQL, see 1.16.
d148 1
a148 1
       patches. If you need help checking the SQL standard, see 1.17.
d151 1
a151 3
       approach (also see
       http://www.ibm.com/developerworks/linux/library/l-clear-code/?ca=d
       gr-FClnxw01linuxcodetips).
d165 1
a165 19
  1.6) How is a patch reviewed?
  
   Patch committers check several things before applying a patch:
     * Patch follows the SQL standard or community agreed-upon behavior
     * Style merges seamlessly into the surrounding code
     * Written as simply and efficiently as possible
     * Uses the available PostgreSQL subsystems properly
     * Contains sufficient comments
     * Contains code that works on all supported operating systems
     * Has proper documentation
     * Passes all regression tests, and if needed, adds new ones
     * Behaves as expected, even under unusual cirumstances
     * Contains no reliability risks
     * Does not overly complicate the source code
     * If performance-related, has a measureable performance benefit
     * Is of sufficient usefulness to the average PostgreSQL user
     * Follows existing PostgreSQL coding standards
       
  1.7) Where can I learn more about the code?
d172 1
a172 1
  1.8) How do I download/update the current source tree?
d183 1
a183 1
  1.9) How do I test my changes?
d226 1
a226 1
  1.10) What tools are available for developers?
d319 1
a319 1
  1.11) What books are good for developers?
d321 9
a329 8
   There are five good books:
     * An Introduction to Database Systems, by C.J. Date, Addison, Wesley
     * A Guide to the SQL Standard, by C.J. Date, et. al, Addison, Wesley
     * Fundamentals of Database Systems, by Elmasri and Navathe
     * Transaction Processing, by Jim Gray, Morgan, Kaufmann
     * Transactional Information Systems by Gerhard Weikum, Kaufmann
       
  1.12) What is configure all about?
d351 1
a351 1
  1.13) How do I add a new port?
d368 1
a368 1
  1.14) Why don't you use threads, raw devices, async-I/O, <insert your
d394 1
a394 1
  1.15) How are RPMs packaged?
d475 1
a475 1
  1.16) How are CVS branches managed?
d534 1
a534 1
  1.17) Where can I get a copy of the SQL standards?
d551 1
a551 1
  1.18) Where can I get technical assistance?
d564 1
a564 1
  1.19) How do I get involved in PostgreSQL web site development?
d572 1
a572 1
  1.20) Why haven't you replaced CVS with SVN, Git, Monotone, VSS, <insert your
d682 2
a683 2
          return the data (a pointer, integer or OID respectively) of
          list cell i.
d686 1
a686 1
          return the next list cell after i.
d689 5
a693 5
          loop through list, assigning each list cell to i. It is
          important to note that i is a ListCell *, not the data in the
          List element. You need to use lfirst(i) to get at the data.
          Here is a typical code snippet that loops through a List
          containing Var *'s and processes each one:
d695 1
a695 2

    List        *list;
d710 1
a710 1
          add node to the end of list.
d712 2
a713 2
   list_concat(list1, list2)
          Concatenate list2 on to the end of list1.
d715 1
a715 1
   list_length(list)
d718 2
a719 2
   list_nth(list, i)
          return the i'th element in list, counting from zero.
d721 3
a723 3
   lcons_int, ...
          There are integer versions of these: lcons_int, lappend_int,
          etc. Also versions for OID lists: lcons_oid, lappend_oid, etc.
d742 1
a742 1
   The structures passed around in the parser, rewriter, optimizer, and
d748 1
a748 1
   new field. mkid is helpful with this (see 1.10).
@


1.117.2.4
log
@Replace developer FAQ with a reference to the wiki, which is where
it now lives (per discussion). Leave the other FAQs alone for now.
@
text
@a0 1
The developer FAQ can be found on the PostgreSQL wiki:
d2 841
a842 1
  http://wiki.postgresql.org/wiki/Development_information
@


1.116
log
@Attached files fix the link problem in FAQ_DEV.html, remove some parts
related to website development and change the link to the FAQ_DEV.html.

Devrim GUNDUZ
@
text
@d4 1
a4 1
   Last updated: Tue Oct 17 08:54:26 EDT 2006
d107 1
a107 1
   http://momjian.postgresql.org/cgi-bin/pgpatches2.
@


1.115
log
@I updated RPM related parts in FAQ_DEV against HEAD to be more current.

Devrim GUNDUZ
@
text
@d4 1
a4 1
   Last updated: Mon Oct 16 15:24:36 EDT 2006
d9 1
a9 1
   http://www.postgresql.org/files/documentation/faqs/FAQ_DEV.html.
d563 1
a563 4
   for the next version of the website is under the "portal" module. You
   will also find code for the "techdocs" website if you would like to
   contribute to that. A temporary todo list for current website
   development issues is available at http://xzilla.postgresql.org/todo
@


1.114
log
@HTLM cleanup.
@
text
@d4 1
a4 1
   Last updated: Wed Sep 6 20:12:13 EDT 2006
d389 1
a389 1
   This was written by Lamar Owen:
d391 1
a391 1
   2001-05-03
d394 1
a394 1
   requires me to know how much experience you have with the whole RPM
d396 1
a396 1
   obvious simple answer is that I maintain:
d409 18
a426 10
   I then download and build on as many different canonical distributions
   as I can -- currently I am able to build on Red Hat 6.2, 7.0, and 7.1
   on my personal hardware. Occasionally I receive opportunity from
   certain commercial enterprises such as Great Bridge and PostgreSQL,
   Inc. to build on other distributions.
   
   I test the build by installing the resulting packages and running the
   regression tests. Once the build passes these tests, I upload to the
   postgresql.org ftp server and make a release announcement. I am also
   responsible for maintaining the RPM download area on the ftp site.
d428 1
a428 1
   You'll notice I said 'canonical' distributions above. That simply
d441 23
a463 33
   For a time I built on Mandrake for RedHat consumption -- no more.
   Nonstandard RPM building systems are worse than useless. Which is not
   to say that Mandrake is useless! By no means is Mandrake useless --
   unless you are building Red Hat RPMs -- and Red Hat is useless if
   you're trying to build Mandrake or SuSE RPMs, for that matter. But I
   would be foolish to use 'Lamar Owen's Super Special RPM Blend Distro
   0.1.2' to build for public consumption! :-)
   
   I _do_ attempt to make the _source_ RPM compatible with as many
   distributions as possible -- however, since I have limited resources
   (as a volunteer RPM maintainer) I am limited as to the amount of
   testing said build will get on other distributions, architectures, or
   systems.
   
   And, while I understand people's desire to immediately upgrade to the
   newest version, realize that I do this as a side interest -- I have a
   regular, full-time job as a broadcast
   engineer/webmaster/sysadmin/Technical Director which occasionally
   prevents me from making timely RPM releases. This happened during the
   early part of the 7.1 beta cycle -- but I believe I was pretty much on
   the ball for the Release Candidates and the final release.
   
   I am working towards a more open RPM distribution -- I would dearly
   love to more fully document the process and put everything into CVS --
   once I figure out how I want to represent things such as the spec file
   in a CVS form. It makes no sense to maintain a changelog, for
   instance, in the spec file in CVS when CVS does a better job of
   changelogs -- I will need to write a tool to generate a real spec file
   from a CVS spec-source file that would add version numbers, changelog
   entries, etc to the result before building the RPM. IOW, I need to
   rethink the process -- and then go through the motions of putting my
   long RPM history into CVS one version at a time so that version
   history information isn't lost.
d466 1
a466 13
   there was a large cry for it to happen, I don't believe it should.
   PostgreSQL is very platform-agnostic -- and I like that. Including the
   RPM stuff as part of the Official Tarball (TM) would, IMHO, slant that
   agnostic stance in a negative way. But maybe I'm too sensitive to
   that. I'm not opposed to doing that if that is the consensus of the
   core group -- and that would be a sneaky way to get the stuff into CVS
   :-). But if the core group isn't thrilled with the idea (and my
   instinct says they're not likely to be), I am opposed to the idea --
   not to keep the stuff to myself, but to not hinder the
   platform-neutral stance. IMHO, of course.
   
   Of course, there are many projects that DO include all the files
   necessary to build RPMs from their Official Tarball (TM).
@


1.113
log
@Update emacs info for FAQ_DEV.

Andrew Dunstan
@
text
@d4 1
a4 1
   Last updated: Wed Sep 6 20:08:24 EDT 2006
d291 4
a294 3
   The tools directory of the latest sources contains sample settings
   that can be used with the emacs, xemacs and vim editors, that assist
   in keeping to PostgreSQL coding standards.
@


1.112
log
@Update tools directory name.
@
text
@d4 1
a4 1
   Last updated: Wed Sep 6 18:02:57 EDT 2006
d280 3
a282 3
   Our standard format is to indent each code level with one tab, where
   each tab is four spaces. You will need to set your editor to display
   tabs as four spaces:
a289 33
    emacs:
        M-x set-variable tab-width

        or

        (c-add-style "pgsql"
                '("bsd"
                        (indent-tabs-mode . t)
                        (c-basic-offset   . 4)
                        (tab-width . 4)
                        (c-offsets-alist .
                                ((case-label . +)))
                )
                nil ) ; t = set this style, nil = don't

        (defun pgsql-c-mode ()
                (c-mode)
                (c-set-style "pgsql")
        )

        and add this to your autoload list (modify file path in macro):

        (setq auto-mode-alist
                (cons '("\\`/home/andrew/pgsql/.*\\.[chyl]\\'" . pgsql-c-mode)
                auto-mode-alist))
        or
            /*
             * Local variables:
             *  tab-width: 4
             *  c-indent-level: 4
             *  c-basic-offset: 4
             * End:
             */
d291 3
@


1.111
log
@Fix wording, per Neil.
@
text
@d4 1
a4 1
   Last updated: Fri Aug 11 23:48:27 EDT 2006
d128 1
a128 1
       src/tools/makediff/difforig useful. (Unified diffs are only
@


1.110
log
@Add Neil's presentation to FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Fri Aug 11 15:18:31 EDT 2006
d144 1
a144 1
       thoughly. Try to test the feature in all conceivable scenarios.
d295 1
a295 22
(add-hook 'c-mode-hook
          (function
           (lambda nil
             (if (string-match "pgsql" buffer-file-name)
                 (progn
                   (c-set-style "bsd")
                   (setq c-basic-offset 4)
                   (setq tab-width(add-hook 'c-mode-hook
          (function
           (lambda nil
             (if (string-match "pgsql" buffer-file-name)
                 (progn
                   (c-set-style "bsd")
                   (setq c-basic-offset 4)
                   (setq tab-width(add-hook 'c-mode-hook
          (function
           (lambda nil
             (if (string-match "pgsql" buffer-file-name)
                 (progn
                   (c-set-style "bsd")
                   (setq c-basic-offset 4)
                   (setq tab-width        (c-add-style "pgsql"
@


1.109
log
@Add URL of code presentation to developers FAQ.
@
text
@d4 1
a4 1
   Last updated: Tue Jul 11 13:01:46 EDT 2006
d295 22
a316 1
        (c-add-style "pgsql"
@


1.108
log
@Update my email address.
@
text
@d4 1
a4 1
   Last updated: Sun Jun 18 15:33:56 EDT 2006
d162 2
a163 1
   http://www.postgresql.org/developer.
@


1.107
log
@Spelling fix.

Robert Treat
@
text
@d4 1
a4 1
   Last updated: Thu Jun 8 09:45:18 EDT 2006
d6 1
a6 1
   Current maintainer: Bruce Momjian (pgman@@candle.pha.pa.us)
@


1.106
log
@Update standards URL.

Robert Treat
@
text
@d4 1
a4 1
   Last updated: Fri May 5 05:51:42 EDT 2006
@


1.105
log
@Update text file.
@
text
@d4 1
a4 1
   Last updated: Wed Mar 1 17:24:48 EST 2006
d578 1
a578 1
     * SQL:2003 http://www.wiscorp.com/sql/sql_2003_standard.zip
@


1.104
log
@Spell fix.  Andrew.
@
text
@d4 1
a4 1
   Last updated: Sat Dec 24 14:29:33 EST 2005
d111 46
a156 17
   Generate the patch in contextual diff format. If you are unfamiliar
   with this, you might find the script src/tools/makediff/difforig
   useful. Unified diffs are only preferrable if the file changes are
   single-line changes and do not rely on the surrounding lines.
   
   Ensure that your patch is generated against the most recent version of
   the code. If it is a patch adding new functionality, the most recent
   version is CVS HEAD; if it is a bug fix, this will be the most
   recently version of the branch which suffers from the bug (for more on
   branches in PostgreSQL, see 1.15).
   
   Finally, submit the patch to pgsql-patches@@postgresql.org. It will be
   reviewed by other contributors to the project and will be either
   accepted or sent back for further work. Also, please try to include
   documentation changes as part of the patch. If you can't do that, let
   us know and we will manually update the documentation when the patch
   is applied.
@


1.103
log
@Update why unified diff is _sometimes_ better.
@
text
@d4 1
a4 1
   Last updated: Sat Dec 24 13:36:54 EST 2005
d114 1
a114 1
   single-line changes and do not rely on the surrouding lines.
@


1.102
log
@Fix markup italics problem.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 22 10:17:51 EST 2005
d113 2
a114 1
   useful.
@


1.101
log
@Update item tags.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 22 10:17:05 EST 2005
@


1.100
log
@Change to using "id=" HTML tags instead of "name=" tags.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 22 10:13:04 EST 2005
@


1.99
log
@Add mention of errfinish.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 27 09:48:14 EDT 2005
@


1.99.2.1
log
@Update 8.1.X FAQs.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 22 10:17:51 EST 2005
@


1.99.2.2
log
@Stamp release 8.1.2.
@
text
@d4 1
a4 1
   Last updated: Sat Dec 24 14:29:33 EST 2005
d113 1
a113 2
   useful. Unified diffs are only preferrable if the file changes are
   single-line changes and do not rely on the surrounding lines.
@


1.99.2.3
log
@Update FAQ_DEV text file.
@
text
@d4 1
a4 1
   Last updated: Wed Mar 1 17:24:48 EST 2006
d111 17
a127 46
   You will need to submit the patch to pgsql-patches@@postgresql.org. It
   will be reviewed by other contributors to the project and will be
   either accepted or sent back for further work. To help ensure your
   patch is reviewed and committed in a timely fashion, please try to
   make sure your submission conforms to the following guidelines:
    1. Ensure that your patch is generated against the most recent
       version of the code, which for developers is CVS HEAD. For more on
       branches in PostgreSQL, see 1.15.
    2. Try to make your patch as readable as possible by following the
       project's code-layout conventions. This makes it easier for the
       reviewer, and there's no point in trying to layout things
       differently than pgindent. Also avoid unnecessary whitespace
       changes because they just distract the reviewer, and formatting
       changes will be removed by the next run of pgindent.
    3. The patch should be generated in contextual diff format (diff -c
       and should be applicable from the root directory. If you are
       unfamiliar with this, you might find the script
       src/tools/makediff/difforig useful. (Unified diffs are only
       preferable if the file changes are single-line changes and do not
       rely on surrounding lines.)
    4. PostgreSQL is licensed under a BSD license, so any submissions
       must conform to the BSD license to be included. If you use code
       that is available under some other license that is BSD compatible
       (eg. public domain) please note that code in your email submission
    5. Confirm that your changes can pass the regression tests. If your
       changes are port specific, please list the ports you have tested
       it on.
    6. Provide an implementation overview, preferably in code comments.
       Following the surrounding code commenting style is usually a good
       approach.
    7. New feature patches should also be accompanied by documentation
       patches. If you need help checking the SQL standard, see 1.16.
    8. If you are adding a new feature, confirm that it has been tested
       thoughly. Try to test the feature in all conceivable scenarios.
    9. If it is a performance patch, please provide confirming test
       results to show the benefit of your patch. It is OK to post
       patches without this information, though the patch will not be
       applied until somebody has tested the patch and found a
       significant performance improvement.
       
   Even if you pass all of the above, the patch might still be rejected
   for other reasons. Please be prepared to listen to comments and make
   modifications.
   
   You will be notified via email when the patch is applied, and your
   name will appear in the next version of the release notes.
@


1.99.2.4
log
@Backpatch FAQs to 8.1.X.
@
text
@d4 1
a4 1
   Last updated: Fri May 5 05:51:42 EDT 2006
d578 1
a578 1
     * SQL:2003 http://www.wiscorp.com/sql_2003_standard.zip
@


1.99.2.5
log
@Backpatch FAQs to 8.1.X.
@
text
@d4 1
a4 1
   Last updated: Wed Sep 6 20:12:13 EDT 2006
d6 1
a6 1
   Current maintainer: Bruce Momjian (bruce@@momjian.us)
d128 1
a128 1
       src/tools/make_diff/difforig useful. (Unified diffs are only
d144 1
a144 1
       thoroughly. Try to test the feature in all conceivable scenarios.
d162 1
a162 2
   http://www.postgresql.org/developer. An excellent presentation is at
   http://neilconway.org/talks/hacking/
d279 3
a281 3
   Our standard format BSD style, with each level of code indented one
   tab, where each tab is four spaces. You will need to set your editor
   or file viewer to display tabs as four spaces:
d289 33
a322 4
   The tools/editors directory of the latest sources contains sample
   settings that can be used with the emacs, xemacs and vim editors, that
   assist in keeping to PostgreSQL coding standards.
   
@


1.99.2.6
log
@Replace developer FAQ with a reference to the wiki, which is where
it now lives (per discussion). Leave the other FAQs alone for now.
@
text
@a0 1
The developer FAQ can be found on the PostgreSQL wiki:
d2 814
a815 1
  http://wiki.postgresql.org/wiki/Development_information
@


1.98
log
@Update profile file location.
@
text
@d4 1
a4 1
   Last updated: Mon Sep 19 21:28:08 EDT 2005
d801 7
a807 5
   can set breakpoints in the debugger and issue queries from psql. If
   you are debugging postgres startup, you can set PGOPTIONS="-W n", then
   start psql. This will cause startup to delay for n seconds so you can
   attach to the process with the debugger, set any breakpoints, and
   continue through the startup sequence.
@


1.97
log
@Update patches queue URL, description.
@
text
@d4 1
a4 1
   Last updated: Tue Aug 9 00:56:51 EDT 2005
d809 2
a810 2
   pgsql/data/base/dbname directory. The client profile file will be put
   in the client's current directory. Linux requires a compile with
@


1.96
log
@Re-order items, add mention of how to propose working on a TODO item.
@
text
@d4 1
a4 1
   Last updated: Sat May 14 12:26:01 EDT 2005
d104 1
a104 1
   A web site is maintained for patches that are ready to be applied,
@


1.95
log
@Update FAQ URLs.

Robert Treat
@
text
@d4 1
a4 1
   Last updated: Fri May 6 13:47:54 EDT 2005
d18 2
a19 2
   1.5) Where can I learn more about the code?
   1.6) I've developed a patch, what next?
d97 6
a102 3
   not advisable: others may be working on the same TODO item; you may
   have misunderstood the TODO item; your approach may benefit from the
   review of others.
d109 1
a109 7
  1.5) Where can I learn more about the code?
  
   Other than documentation in the source tree itself, you can find some
   papers/presentations discussing the code at
   http://www.postgresql.org/developer.
   
  1.6) I've developed a patch, what next?
d112 2
a113 1
   with this, you may find the script src/tools/makediff/difforig useful.
d117 1
a117 1
   version is cvs HEAD; if it is a bug fix, this will be the most
d122 11
a132 2
   reviewed by other contributors to the project and may be either
   accepted or sent back for further work.
d140 1
a140 1
   Regular developers may want to take advantage of anonymous access to
d166 1
a166 1
   If you've deliberately changed existing behavior, this change may
d635 4
a638 4
   tuples can be either system cache copies, which may go away after you
   call ReleaseSysCache(), or read directly from disk buffers, which go
   away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
   heap_fetch() case. Or it may be a palloc'ed tuple, that you must
d739 2
a740 2
   files. Find any other places the structure may need code for your new
   field. mkid is helpful with this (see 1.9).
d796 1
a796 1
   interaction problems may not be duplicated.
@


1.94
log
@Adjust question spacing.
@
text
@d88 1
a88 1
   http://developer.postgresql.org/todo.php.
@


1.93
log
@Move info about lack of depencency checking in Makefiles to developer's faq.q
@
text
@d4 1
a4 1
   Last updated: Sat Apr 23 16:52:14 EDT 2005
d26 1
a26 1
   1.13) Why don't you use threads/raw devices/async-I/O, <insert your
d352 2
a353 2
  1.13) Why don't you use threads/raw devices/async-I/O, <insert your favorite
  wizz-bang feature here>?
@


1.92
log
@Add item about server-side debugging.
@
text
@d4 1
a4 1
   Last updated: Sat Apr 23 14:57:40 EDT 2005
d176 5
@


1.91
log
@Fix typo on URL.
@
text
@d4 1
a4 1
   Last updated: Sun Mar 13 22:07:18 EST 2005
d45 1
d766 34
@


1.90
log
@Remove CENTER tag.
@
text
@d4 1
a4 1
   Last updated: Sun Mar 13 14:27:45 EST 2005
@


1.89
log
@Here's the patch to fix a lot of markup errors in the HTML FAQs. Doesn't
change content (at least not supposed to).

Magnus Hagander
@
text
@d4 1
a4 1
   Last updated: Fri Mar 11 16:43:05 EST 2005
d47 2
a48 2
                             General Questions
                                      
@


1.88
log
@Fix typos.

Hashem Masoud
@
text
@d4 1
a4 1
   Last updated: Fri Mar 11 08:09:23 EST 2005
d12 2
a13 2
                             General Questions
                                      
d34 2
a35 2
                            Technical Questions
                                      
d567 2
a568 2
                            Technical Questions
                                      
@


1.87
log
@Fix typos.

Robert Treat
@
text
@d4 1
a4 1
   Last updated: Fri Mar 11 06:58:51 EST 2005
d49 1
a49 1
  1.1) How go I get involved in PostgreSQL development?
d556 1
a556 1
  1.18) How go I get involved in PostgreSQL web site development?
@


1.86
log
@Fix typos.

Robert Treat
@
text
@d4 1
a4 1
   Last updated: Fri Mar 11 06:43:43 EST 2005
@


1.85
log
@Fix typo.
@
text
@d4 1
a4 1
   Last updated: Fri Mar 11 06:42:00 EST 2005
d142 1
a142 1
   the latest verion of the code and that it does not generate compiler
d158 1
a158 1
   If you've deliberately changed existing behaviour, this change may
d385 1
a385 1
    3. Any other ancilliary scripts and files;
d503 1
a503 1
   To get a past branch, you cd to whereever you want it and say
d563 1
a563 1
   will al so find code for the "techdocs" website if you would like to
@


1.84
log
@Add comma.
@
text
@d4 1
a4 1
   Last updated: Tue Mar 8 08:27:31 EST 2005
d661 1
a661 1
          return the data (a point, inteter and OID respectively) at list
@


1.83
log
@Fix markup of URL.
@
text
@d4 1
a4 1
   Last updated: Mon Mar 7 22:52:51 EST 2005
d101 1
a101 1
   http://momjian.postgresql.org/cgi-bin/pgpatches and those that are
@


1.82
log
@Add URL for patches queues.
@
text
@d4 1
a4 1
   Last updated: Mon Mar 7 20:15:31 EST 2005
d101 2
a102 3
   href="http://momjian.postgresql.org/cgi-bin/pgpatches">
   http://momjian.postgresql.org/cgi-bin/pgpatches
   and those that are being kept for the next release,
@


1.81
log
@Update URL's to point to new site main location.
@
text
@d4 1
a4 1
   Last updated: Wed Jan 5 17:36:58 EST 2005
d100 6
@


1.81.4.1
log
@Here's the patch to fix a lot of markup errors in the HTML FAQs. Doesn't
change content (at least not supposed to).

Magnus Hagander
@
text
@d4 1
a4 1
   Last updated: Fri Mar 11 16:43:05 EST 2005
d12 2
a13 2
General Questions

d34 2
a35 2
Technical Questions

d49 1
a49 1
  1.1) How do I get involved in PostgreSQL development?
a99 5
   A web site is maintained for patches that are ready to be applied,
   http://momjian.postgresql.org/cgi-bin/pgpatches, and those that are
   being kept for the next release,
   http://momjian.postgresql.org/cgi-bin/pgpatches2.
   
d137 1
a137 1
   the latest version of the code and that it does not generate compiler
d153 1
a153 1
   If you've deliberately changed existing behavior, this change may
d380 1
a380 1
    3. Any other ancillary scripts and files;
d498 1
a498 1
   To get a past branch, you cd to wherever you want it and say
d551 1
a551 1
  1.18) How do I get involved in PostgreSQL web site development?
d558 1
a558 1
   will also find code for the "techdocs" website if you would like to
d562 2
a563 2
Technical Questions

d656 1
a656 1
          return the data (a point, integer and OID respectively) at list
@


1.81.4.2
log
@Backpatch FAQ's to 8.0.X.
@
text
@d4 1
a4 1
   Last updated: Sun Mar 13 22:07:18 EST 2005
d47 2
a48 2
General Questions

@


1.81.4.3
log
@Backpatch FAQ's to 8.0.X for release.
@
text
@d4 1
a4 1
   Last updated: Fri May 6 13:47:54 EDT 2005
d26 1
a26 1
   1.13) Why don't you use threads, raw devices, async-I/O, <insert your
a44 1
   2.8) What debugging features are available?
a174 5
   Keep in mind the Makefiles do not have the proper dependencies for
   include files. You have to do a make clean and then another make. If
   you are using GCC you can use the --enable-depend option of configure
   to have the compiler compute the dependencies automatically.
   
d346 2
a347 2
  1.13) Why don't you use threads, raw devices, async-I/O, <insert your
  favorite wizz-bang feature here>?
a764 34
   
  2.8) What debugging features are available?
  
   First, try running configure with the --enable-cassert option, many
   assert()s monitor the progress of the backend and halt the program
   when something unexpected occurs.
   
   The postmaster has a -d option that allows even more detailed
   information to be reported. The -d option takes a number that
   specifies the debug level. Be warned that high debug level values
   generate large log files.
   
   If the postmaster is not running, you can actually run the postgres
   backend from the command line, and type your SQL statement directly.
   This is recommended only for debugging purposes. If you have compiled
   with debugging symbols, you can use a debugger to see what is
   happening. Because the backend was not started from postmaster, it is
   not running in an identical environment and locking/backend
   interaction problems may not be duplicated.
   
   If the postmaster is running, start psql in one window, then find the
   PID of the postgres process used by psql using SELECT
   pg_backend_pid(). Use a debugger to attach to the postgres PID. You
   can set breakpoints in the debugger and issue queries from psql. If
   you are debugging postgres startup, you can set PGOPTIONS="-W n", then
   start psql. This will cause startup to delay for n seconds so you can
   attach to the process with the debugger, set any breakpoints, and
   continue through the startup sequence.
   
   You can also compile with profiling to see what functions are taking
   execution time. The backend profile files will be deposited in the
   pgsql/data/base/dbname directory. The client profile file will be put
   in the client's current directory. Linux requires a compile with
   -DLINUX_PROFILE for proper profiling.
@


1.81.4.4
log
@Update FAQ URLs.

Robert Treat
@
text
@d88 1
a88 1
   http://www.postgresql.org/docs/faqs.TODO.html.
@


1.81.4.5
log
@Update Chinese FAQ to xhtml.
@
text
@d4 1
a4 1
   Last updated: Sat May 14 12:26:01 EDT 2005
d18 2
a19 2
   1.5) I've developed a patch, what next?
   1.6) Where can I learn more about the code?
d97 3
a99 6
   not advisable because others might be working on the same TODO item,
   or you might have misunderstood the TODO item. In the email, discuss
   both the internal implementation method you plan to use, and any
   user-visible changes (new syntax, etc). For complex patches, it is
   important to get community feeback on your proposal before starting
   work. Failure to do so might mean your patch is rejected.
d106 7
a112 1
  1.5) I've developed a patch, what next?
d115 1
a115 2
   with this, you might find the script src/tools/makediff/difforig
   useful.
d119 1
a119 1
   version is CVS HEAD; if it is a bug fix, this will be the most
d124 2
a125 11
   reviewed by other contributors to the project and will be either
   accepted or sent back for further work. Also, please try to include
   documentation changes as part of the patch. If you can't do that, let
   us know and we will manually update the documentation when the patch
   is applied.
   
  1.6) Where can I learn more about the code?
  
   Other than documentation in the source tree itself, you can find some
   papers/presentations discussing the code at
   http://www.postgresql.org/developer.
d133 1
a133 1
   Regular developers might want to take advantage of anonymous access to
d159 1
a159 1
   If you've deliberately changed existing behavior, this change might
d628 4
a631 4
   tuples can be either system cache copies, which might go away after
   you call ReleaseSysCache(), or read directly from disk buffers, which
   go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in
   the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
d732 2
a733 2
   files. Find any other places the structure might need code for your
   new field. mkid is helpful with this (see 1.9).
d789 1
a789 1
   interaction problems might not be duplicated.
@


1.81.4.6
log
@Update FAQ's in 8.0.X branch.
@
text
@d4 1
a4 1
   Last updated: Mon Sep 19 21:28:08 EDT 2005
d104 1
a104 1
   A web site is maintained for patches awaiting review,
d809 2
a810 2
   pgsql/data directory. The client profile file will be put in the
   client's current directory. Linux requires a compile with
@


1.81.4.7
log
@Backpatch FAQ's for 8.0.X.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 27 09:48:14 EDT 2005
d801 5
a805 7
   can set breakpoints in the debugger and issue queries from the other.
   If you are looking to find the location that is generating an error or
   log message, set a breakpoint at errfinish. psql. If you are debugging
   postgres startup, you can set PGOPTIONS="-W n", then start psql. This
   will cause startup to delay for n seconds so you can attach to the
   process with the debugger, set any breakpoints, and continue through
   the startup sequence.
@


1.81.4.8
log
@Replace developer FAQ with a reference to the wiki, which is where
it now lives (per discussion). Leave the other FAQs alone for now.
@
text
@a0 1
The developer FAQ can be found on the PostgreSQL wiki:
d2 812
a813 1
  http://wiki.postgresql.org/wiki/Development_information
@


1.80
log
@Update date stamp.
@
text
@d4 1
a4 1
   Last updated: Wed Jan 5 12:52:11 EST 2005
d104 1
a104 1
   http://developer.postgresql.org.
@


1.79
log
@Update URLs.
@
text
@d4 1
a4 1
   Last updated: Wed Dec 1 16:11:11 EST 2006
@


1.78
log
@Update with Gavin's additions.
@
text
@d9 1
a9 1
   http://www.PostgreSQL.org/docs/faqs/FAQ_DEV.html.
d104 1
a104 1
   http://developers.postgresql.org.
d669 1
a669 1
   List                *list;
@


1.77
log
@Add web development faq item.
@
text
@d4 1
a4 1
   Last updated: Sat Nov 27 01:02:35 EST 2004
d15 12
a26 8
   1.2) How do I add a feature or fix a bug?
   1.3) How do I download/update the current source tree?
   1.4) How do I test my changes?
   1.5) What tools are available for developers?
   1.6) What books are good for developers?
   1.7) What is configure all about?
   1.8) How do I add a new port?
   1.9) Why don't you use threads/raw devices/async-I/O, <insert your
d28 5
a32 4
   1.10) How are RPM's packaged?
   1.11) How are CVS branches handled?
   1.12) Where can I get a copy of the SQL standards?
   1.1) How do I get involved in PostgreSQL web site development?
d51 65
a115 1
   This was written by Lamar Owen:
d117 3
a119 2
   2001-06-22
   What open source development process is used by the PostgreSQL team?
d121 1
a121 76
   Read HACKERS for six months (or a full release cycle, whichever is
   longer). Really. HACKERS _is_the process. The process is not well
   documented (AFAIK -- it may be somewhere that I am not aware of) --
   and it changes continually.
   What development environment (OS, system, compilers, etc) is required
   to develop code?
   
   Developers Corner on the website has links to this information. The
   distribution tarball itself includes all the extra tools and documents
   that go beyond a good Unix-like development environment. In general, a
   modern unix with a modern gcc, GNU make or equivalent, autoconf (of a
   particular version), and good working knowledge of those tools are
   required.
   What areas need support?
   
   The TODO list.
   
   You've made the first step, by finding and subscribing to HACKERS.
   Once you find an area to look at in the TODO, and have read the
   documentation on the internals, etc, then you check out a current
   CVS,write what you are going to write (keeping your CVS checkout up to
   date in the process), and make up a patch (as a context diff only) and
   send to the PATCHES list, prefereably.
   
   Discussion on the patch typically happens here. If the patch adds a
   major feature, it would be a good idea to talk about it first on the
   HACKERS list, in order to increase the chances of it being accepted,
   as well as toavoid duplication of effort. Note that experienced
   developers with a proven track record usually get the big jobs -- for
   more than one reason. Also note that PostgreSQL is highly portable --
   nonportable code will likely be dismissed out of hand.
   
   Once your contributions get accepted, things move from there.
   Typically, you would be added as a developer on the list on the
   website when one of the other developers recommends it. Membership on
   the steering committee is by invitation only, by the other steering
   committee members, from what I have gathered watching froma distance.
   
   I make these statements from having watched the process for over two
   years.
   
   To see a good example of how one goes about this, search the archives
   for the name 'Tom Lane' and see what his first post consisted of, and
   where he took things. In particular, note that this hasn't been _that_
   long ago -- and his bugfixing and general deep knowledge with this
   codebase is legendary. Take a few days to read after him. And pay
   special attention to both the sheer quantity as well as the
   painstaking quality of his work. Both are in high demand.
   
  1.2) How do I add a feature or fix a bug?
  
   The source code is over 350,000 lines. Many fixes/features are
   isolated to one specific area of the code. Others require knowledge of
   much of the source. If you are confused about where to start, ask the
   hackers list, and they will be glad to assess the complexity and give
   pointers on where to start.
   
   Another thing to keep in mind is that many fixes and features can be
   added with surprisingly little code. I often start by adding code,
   then looking at other areas in the code where similar things are done,
   and by the time I am finished, the patch is quite small and compact.
   
   When adding code, keep in mind that it should use the existing
   facilities in the source, for performance reasons and for simplicity.
   Often a review of existing code doing similar things is helpful.
   
   The usual process for source additions is:
     * Review the TODO list.
     * Discuss hackers the desirability of the fix/feature.
     * How should it behave in complex circumstances?
     * How should it be implemented?
     * Submit the patch to the patches list.
     * Answer email questions.
     * Wait for the patch to be applied.
       
  1.3) How do I download/update the current source tree?
d125 49
a173 39
   ftp.postgresql.org. For regular developers, you can use CVS. CVS
   allows you to download the source tree, then occasionally update your
   copy of the source tree with any new changes. Using CVS, you don't
   have to download the entire source each time, only the changed files.
   Anonymous CVS does not allows developers to update the remote source
   tree, though privileged developers can do this. There is a CVS section
   (http://developer.postgresql.org/docs/postgres/cvs.html) in our
   documentation that describes how to use remote CVS. You can also use
   CVSup, which has similarly functionality, and is available from
   ftp.postgresql.org.
   
   To update the source tree, there are two ways. You can generate a
   patch against your current source tree, perhaps using the make_diff
   tools mentioned above, and send them to the patches list. They will be
   reviewed, and applied in a timely manner. If the patch is major, and
   we are in beta testing, the developers may wait for the final release
   before applying your patches.
   
   For hard-core developers, Marc(scrappy@@postgresql.org) will give you a
   Unix shell account on postgresql.org, so you can use CVS to update the
   main source tree, or you can ftp your files into your account, patch,
   and cvs install the changes directly into the source tree.
   
  1.4) How do I test my changes?
  
   First, use psql to make sure it is working as you expect. Then run
   src/test/regress and get the output of src/test/regress/checkresults
   with and without your changes, to see that your patch does not change
   the regression test in unexpected ways. This practice has saved me
   many times. The regression tests test the code in ways I would never
   do, and has caught many bugs in my patches. By finding the problems
   now, you save yourself a lot of debugging later when things are
   broken, and you can't figure out when it happened.
   
  1.5) What tools are available for developers?
  
   Aside from the User documentation mentioned in the regular FAQ, there
   are several development tools available. First, all the files in the
   /tools directory are designed for developers.
a174 1
    SQL_keywords    standard SQL'92 keywords
d177 2
d183 2
d190 1
a190 3
    mkldexport      create AIX exports file
    pgindent        indents C source files
    pgjindent       indents Java source files
d192 8
a199 1
    unused_oids     in pgsql/src/include/catalog
d201 1
a201 2
   Let me note some of these. If you point your browser at the
   file:/usr/local/src/pgsql/src/tools/backend/index.html directory, you
d218 2
a219 5
   Third, you need to get id-utils from:
    ftp://alpha.gnu.org/gnu/id-utils-3.2d.tar.gz
    ftp://tug.org/gnu/id-utils-3.2d.tar.gz
    ftp://ftp.enst.fr/pub/gnu/gnits/id-utils-3.2d.tar.gz

d221 1
a221 2
   created that can be rapidly queried like grep or edited. Others prefer
   glimpse.
d223 7
a229 3
   make_diff has tools to create patch diff files that can be applied to
   the distribution. This produces context diffs, which is our preferred
   format.
d277 1
a277 1
   constent coding style.
d292 1
a292 1
  1.6) What books are good for developers?
d300 1
a300 1
   written by Jim Gray at http://www.benchmarkresources.com.
d302 1
a302 1
  1.7) What is configure all about?
d324 1
a324 1
  1.8) How do I add a new port?
d341 1
a341 1
  1.9) Why don't you use threads/raw devices/async-I/O, <insert your favorite
d367 1
a367 1
  1.10) How are RPM's packaged?
d462 1
a462 1
  1.11) How are CVS branches managed?
d521 1
a521 1
  1.12) Where can I get a copy of the SQL standards?
d538 14
a551 1
  1.13) How go I get involved in PostgreSQL web site development?
d655 3
a657 2
   lfirst(i)
          return the data at list element i.
d669 2
a670 1
List *i, *list;
d719 4
a722 3
   those structures. Make sure you add support for your new field to
   these files. Find any other places the structure may need code for
   your new field. mkid is helpful with this (see above).
@


1.76
log
@Update wording.
@
text
@d4 1
a4 1
   Last updated: Fri Oct 15 12:26:50 EDT 2004
d27 1
d526 11
@


1.75
log
@New wording on the three standards.
@
text
@d4 1
a4 1
   Last updated: Fri Oct 15 12:10:14 EDT 2004
d512 1
a512 1
   download from:
@


1.74
log
@Typo cleanup.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 17:47:04 EDT 2004
d510 3
a512 3
   There are three major standards: SQL-92, SQL:1999, and SQL:2003. These
   standards are endorsed by ANSI and ISO. Draft versions can be download
   from:
@


1.73
log
@Update standards names.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 17:46:01 EDT 2004
d522 1
a522 1
     * http://www.contrib.andrew.cmu.edu/~shadow/sql.html#syntax (SQL92)
@


1.72
log
@Update 2003 as an official standard.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 17:39:02 EDT 2004
d510 1
a510 1
   There are three major standards: SQL-92, SQL-99, and SQL:2003. These
d514 1
a514 1
     * SQL-99
@


1.71
log
@Add "draft".
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:14:50 EDT 2004
d510 9
a518 8
   There are two major standards, SQL92 and SQL99. These standards are
   endorsed by ANSI and ISO. A draft of the SQL92 standard is available
   at http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt. A draft
   of the SQL99 standard is at
   http://www.cse.iitb.ac.in/dbms/Data/Papers-Other/SQL1999/ansi-iso-9075
   -2-1999.pdf. The draft SQL 2003 standard is at
   http://www.wiscorp.com/sql/sql_2003_standard.zip
   
@


1.70
log
@Reorder links.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:12:54 EDT 2004
d515 1
a515 1
   -2-1999.pdf. The SQL 2003 standard is at
@


1.69
log
@More URL updates.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:10:20 EDT 2004
d519 1
d521 1
a521 2
     * http://troels.arvin.dk/db/rdbms/links/#standards
     * http://www.contrib.andrew.cmu.edu/~shadow/sql.html#syntax
@


1.68
log
@Update markup.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:08:23 EDT 2004
d512 1
a512 1
   at http://www.contrib.andrew.cmu.edu/~shadow/sql.html#syntax. A draft
@


1.67
log
@New urls.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:07:40 EDT 2004
@


1.66
log
@Working improvement.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:04:04 EDT 2004
d521 1
@


1.65
log
@Fix markup.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:01:55 EDT 2004
d510 4
a513 5
   There are two pertinent standards, SQL92 and SQL99. These standards
   are endorsed by ANSI and ISO. A draft of the SQL92 standard is
   available at
   http://www.contrib.andrew.cmu.edu/~shadow/sql.html#syntax. A draft of
   the SQL99 standard is at
@


1.64
log
@Add standards URL's.
@
text
@d4 1
a4 1
   Last updated: Thu Oct 14 15:00:26 EDT 2004
@


1.63
log
@Add CVS URL for docs.
@
text
@d4 1
a4 1
   Last updated: Mon Oct 4 11:29:26 EDT 2004
d512 5
a516 5
   available at http://www.contrib.andrew.cmu.edu/~shadow/. The SQL99
   standard must be purchased from ANSI at
   http://webstore.ansi.org/ansidocstore/default.asp. The main standards
   documents are ANSI X3.135-1992 for SQL92 and ANSI/ISO/IEC 9075-2-1999
   for SQL99. The SQL 2003 standards are at
d519 5
a523 3
   A summary of these standards is at
   http://dbs.uni-leipzig.de/en/lokal/standards.pdf.
   
@


1.62
log
@No CVS FAQ, just CVS docs.
@
text
@d4 1
a4 1
   Last updated: Mon Jul 19 16:30:05 EDT 2004
d135 4
a138 3
   in our documentation that describes how to use remote CVS. You can
   also use CVSup, which has similarly functionality, and is available
   from ftp.postgresql.org.
@


1.61
log
@Update date.
@
text
@d4 1
a4 1
   Last updated: Mon Jun 7 11:11:06 EDT 2004
d134 4
a137 4
   tree, though privileged developers can do this. There is a CVS FAQ on
   our web site that describes how to use remote CVS. You can also use
   CVSup, which has similarly functionality, and is available from
   ftp.postgresql.org.
@


1.60
log
@Add SQL 2003 standards.
@
text
@d4 1
a4 1
   Last updated: Wed Apr 7 19:32:25 EDT 2004
@


1.59
log
@Remove bad URL.
@
text
@d4 1
a4 1
   Last updated: Wed Apr 7 18:01:59 EDT 2004
d515 2
a516 2
   for SQL99. The SQL 200X standards are at
   ftp://sqlstandards.org/SC32/WG3/Progression_Documents/FCD
@


1.58
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Wed Apr 7 10:23:31 EDT 2004
d519 1
a519 2
   http://dbs.uni-leipzig.de/en/lokal/standards.pdf and
   http://db.konkuk.ac.kr/present/SQL3.pdf.
@


1.57
log
@Add URL for most current version.
@
text
@d4 1
a4 1
   Last updated: Tue Feb 10 10:16:31 EST 2004
@


1.56
log
@Fix URL.
@
text
@d4 1
a4 1
   Last updated: Sat Nov 29 23:56:43 EST 2003
d8 2
a9 2
   The most recent version of this document can be viewed at the
   postgreSQL Web site, http://www.PostgreSQL.org.
@


1.55
log
@Update FAQ_DEV:  elog => ereport.
@
text
@d4 1
a4 1
   Last updated: Wed Oct 29 21:40:18 EST 2003
@


1.55.2.1
log
@Stamp 7.4.1.

Update 7.4.1 FAQ's to current.
@
text
@d4 1
a4 1
   Last updated: Sat Nov 29 23:56:43 EST 2003
@


1.55.2.2
log
@Brand 7.4.2.  Release notes still need work.
@
text
@d4 1
a4 1
   Last updated: Tue Feb 10 10:16:31 EST 2004
d8 2
a9 2
   The most recent version of this document can be viewed at
   http://www.PostgreSQL.org/docs/faqs/FAQ_DEV.html.
@


1.55.2.3
log
@Replace developer FAQ with a reference to the wiki, which is where
it now lives (per discussion). Leave the other FAQs alone for now.
@
text
@a0 1
The developer FAQ can be found on the PostgreSQL wiki:
d2 715
a716 1
  http://wiki.postgresql.org/wiki/Development_information
@


1.54
log
@Update Emacs settings, from Andrew Dunstan
@
text
@d4 1
a4 1
   Last updated: Mon Jun 2 00:34:39 EDT 2003
d37 1
a37 1
   2.6) What is elog()?
d690 1
a690 1
  2.6) What is elog()?
d692 1
a692 1
   elog() is used to send messages to the front-end, and optionally
d694 8
a701 7
   elog level of DEBUG (levels 1-5), LOG, INFO, NOTICE, ERROR, FATAL, or
   PANIC. NOTICE prints on the user's terminal and the postmaster logs.
   INFO prints only to the user's terminal and LOG prints only to the
   server logs. (These can be changed from postgresql.conf.) ERROR prints
   in both places, and terminates the current query, never returning from
   the call. FATAL terminates the backend process. The remaining
   parameters of elog are a printf-style set of parameters to print.
d703 2
a704 2
   elog(ERROR) frees most memory and open file descriptors so you don't
   need to clean these up before the call.
@


1.53
log
@Add SQL 200X standards URL.
@
text
@d4 1
a4 1
   Last updated: Tue Feb 18 20:38:29 EST 2003
d229 1
d231 15
a245 9
        ; Cmd to set tab stops & indenting for working with PostgreSQL code
             (c-add-style "pgsql"
                      '("bsd"
                                 (indent-tabs-mode . t)
                                 (c-basic-offset   . 4)
                                 (tab-width . 4)
                                 (c-offsets-alist .
                                            ((case-label . +))))
                       t) ; t = set this mode on
d250 2
a251 2
              (cons '("\\`/usr/local/src/pgsql/.*\\.[chyl]\\'" . pgsql-c-mode)
            auto-mode-alist))
@


1.52
log
@New URL.
@
text
@d4 1
a4 1
   Last updated: Tue Feb 18 11:38:00 EST 2003
d508 2
a509 1
   for SQL99.
@


1.51
log
@*** empty log message ***
@
text
@d4 1
a4 1
   Last updated: Fri Feb 14 08:59:10 EST 2003
@


1.50
log
@Create a distinction between Lists of integers and Lists of OIDs, to get
rid of the assumption that sizeof(Oid)==sizeof(int).  This is one small
step towards someday supporting 8-byte OIDs.  For the moment, it doesn't
do much except get rid of a lot of unsightly casts.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 5 16:52:46 EST 2002
@


1.49
log
@Update FAQ_DEV.
@
text
@d646 2
a647 3
          There are integer versions of these: lconsi, lappendi, nthi.
          List's containing integers instead of Node pointers are used to
          hold list of relation object id's and other integer quantities.
@


1.48
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 5 16:49:16 EST 2002
d328 1
a328 1
   wizz-bang features don't provide dramatic improvements. Third, the
d342 3
a344 4
   So, we are not "asleep at the switch" as they say with regard to new
   features, it is just that we are cautious about their adoption. The
   TODO list often contains links to discussions showing our reasoning in
   these areas.
@


1.47
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Sat Nov 2 23:02:16 EST 2002
d22 2
a23 2
   1.9) Why don't you use threads/raw devices/async-I/O, &insert your
   favorite wizz-bang feature here&?
d320 2
a321 2
  1.9) Why don't you use threads/raw devices/async-I/O, &insert your favorite
  wizz-bang feature here&?
@


1.47.2.1
log
@Update TODO/FAQ for 7.3 release.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 5 16:52:46 EST 2002
d22 2
a23 2
   1.9) Why don't you use threads/raw devices/async-I/O, <insert your
   favorite wizz-bang feature here>?
d320 2
a321 2
  1.9) Why don't you use threads/raw devices/async-I/O, <insert your favorite
  wizz-bang feature here>?
d328 1
a328 1
   wizz-bang features don't provide dramatic improvements. Third, they
d342 4
a345 3
   So, we are not ignorant of new features. It is just that we are
   cautious about their adoption. The TODO list often contains links to
   discussions showing our reasoning in these areas.
@


1.47.2.2
log
@Update FAQ's in head and 7.3.X.
@
text
@d4 1
a4 1
   Last updated: Fri Feb 14 08:59:10 EST 2003
d646 3
a648 2
          There are integer versions of these: lconsi, lappendi, etc.
          Also versions for OID lists: lconso, lappendo, etc.
@


1.47.2.3
log
@Update all FAQ's for 7.3.4.
@
text
@d4 1
a4 1
   Last updated: Mon Jun 2 00:34:39 EDT 2003
a228 1

d230 9
a238 15

        (c-add-style "pgsql"
                '("bsd"
                        (indent-tabs-mode . t)
                        (c-basic-offset   . 4)
                        (tab-width . 4)
                        (c-offsets-alist .
                                ((case-label . +)))
                )
                nil ) ; t = set this style, nil = don't

        (defun pgsql-c-mode ()
                (c-mode)
                (c-set-style "pgsql")
        )
d243 2
a244 2
                (cons '("\\`/home/andrew/pgsql/.*\\.[chyl]\\'" . pgsql-c-mode)
                auto-mode-alist))
d508 1
a508 2
   for SQL99. The SQL 200X standards are at
   ftp://sqlstandards.org/SC32/WG3/Progression_Documents/FCD
@


1.46
log
@Changes to documentation and the regression tests for the default
NAMEDATALEN of 64.

Kris Jurka
@
text
@d4 1
a4 1
   Last updated: Tue Aug 13 16:41:02 EDT 2002
d22 2
a23 1
   1.9) Why don't we use threads in the backend?
d320 2
a321 1
  1.9) Why don't we use threads in the backend?
d323 13
a335 1
   There are several reasons threads are not used:
d342 5
@


1.45
log
@Update for longer NAMEDATALEN.
@
text
@d563 1
a563 1
   NAMEDATALEN is 32 bytes.)
@


1.44
log
@Change NAMEDATALEN to 64,  INDEX_MAX_KEYS/MAX_FUNC_ARGS to 32, per discussion on hackers.
@
text
@d4 1
a4 1
   Last updated: Wed Apr 17 01:12:20 EDT 2002
d563 1
a563 1
   NAMEDATALEN is 64 bytes.)
@


1.43
log
@Add SQL92 document name.
@
text
@d563 1
a563 1
   NAMEDATALEN is 32 bytes.)
@


1.42
log
@Update to point directly to ANSI store.
@
text
@d4 1
a4 1
   Last updated: Wed Apr 17 01:09:55 EDT 2002
d489 2
a490 1
   document is ANSI/ISO/IEC 9075-2-1999.
@


1.41
log
@Add mention of standards documents.
@
text
@d4 1
a4 1
   Last updated: Wed Apr 17 00:59:45 EDT 2002
d487 3
a489 2
   standard must be purchased from ANSI at http://www.ansi.org/. The main
   standards document is ANSI/ISO/IEC 9075-2-1999.
@


1.40
log
@Add steps for typical patch.
@
text
@d4 1
a4 1
   Last updated: Tue Apr 16 22:10:03 EDT 2002
d25 1
d481 12
@


1.39
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Mon Feb 25 15:29:28 EST 2002
d99 1
a99 1
   The source code is over 250,000 lines. Many problems/features are
d114 9
@


1.38
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Sat Feb 23 15:09:27 EST 2002
d645 10
a654 6
   elog level of NOTICE, DEBUG, ERROR, or FATAL. NOTICE prints on the
   user's terminal and the postmaster logs. DEBUG prints only in the
   postmaster logs. ERROR prints in both places, and terminates the
   current query, never returning from the call. FATAL terminates the
   backend process. The remaining parameters of elog are a printf-style
   set of parameters to print.
@


1.37
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Fri Feb 1 15:22:54 EST 2002
@


1.36
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Thu Jan 3 03:20:49 EST 2002
d575 1
a575 1
          a typical code snipped that loops through a List containing Var
@


1.35
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Thu Jan 3 03:13:44 EST 2002
@


1.34
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Sat Dec 29 23:31:26 EST 2001
d635 5
a639 5
   we automatically free all memory allocated when a transaction
   completes. This makes it easier to make sure we free memory that gets
   allocated in one place, but only freed much later. There are several
   contexts that memory can be allocated in, and this controls when the
   allocated memory is automatically freed by the backend.
@


1.33
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Sat Dec 29 00:15:44 EST 2001
d244 2
a245 1
   system's utility indent.
@


1.32
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Dec 4 01:20:03 EST 2001
@


1.31
log
@Update FAQ_DEV.
@
text
@d26 2
a27 2
Technical Questions

@


1.30
log
@Update FAQ_DEV.
@
text
@d12 1
a12 1
                                 Questions
d14 17
a30 9
   1) What tools are available for developers?
   2) What books are good for developers?
   3) Why do we use palloc() and pfree() to allocate memory?
   4) Why do we use Node and List to make data structures?
   5) How do I add a feature or fix a bug?
   6) How do I download/update the current source tree?
   7) How do I test my changes?
   7) I just added a field to a structure. What else should I do?
   8) Why are table, column, type, function, view names sometimes
d32 5
a36 10
   9) How do I efficiently access information in tables from the backend
   code?
   10) What is elog()?
   11) What is configure all about?
   12) How do I add a new port?
   13) What is CommandCounterIncrement()?
   14) Why don't we use threads in the backend?
   15) How are RPM's packaged?
   16) How are CVS branches handled?
   17) How do I get involved in PostgreSQL development?
d39 113
a151 1
  1) What tools are available for developers?
d259 1
a259 232
  2) What books are good for developers?
  
   I have four good books, An Introduction to Database Systems, by C.J.
   Date, Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et.
   al, Addison, Wesley, Fundamentals of Database Systems, by Elmasri and
   Navathe, and Transaction Processing, by Jim Gray, Morgan, Kaufmann
   
   There is also a database performance site, with a handbook on-line
   written by Jim Gray at http://www.benchmarkresources.com.
   
  3) Why do we use palloc() and pfree() to allocate memory?
  
   palloc() and pfree() are used in place of malloc() and free() because
   we automatically free all memory allocated when a transaction
   completes. This makes it easier to make sure we free memory that gets
   allocated in one place, but only freed much later. There are several
   contexts that memory can be allocated in, and this controls when the
   allocated memory is automatically freed by the backend.
   
  4) Why do we use Node and List to make data structures?
  
   We do this because this allows a consistent way to pass data inside
   the backend in a flexible way. Every node has a NodeTag which
   specifies what type of data is inside the Node. Lists are groups of
   Nodes chained together as a forward-linked list.
   
   Here are some of the List manipulation commands:
   
   lfirst(i)
          return the data at list element i.
          
   lnext(i)
          return the next list element after i.
          
   foreach(i, list)
          loop through list, assigning each list element to i. It is
          important to note that i is a List *, not the data in the List
          element. You need to use lfirst(i) to get at the data. Here is
          a typical code snipped that loops through a List containing Var
          *'s and processes each one:
          
List *i, *list;

    foreach(i, list)
    {
        Var *var = lfirst(i);

        /* process var here */
    }

   lcons(node, list)
          add node to the front of list, or create a new list with node
          if list is NIL.
          
   lappend(list, node)
          add node to the end of list. This is more expensive that lcons.
          
   nconc(list1, list2)
          Concat list2 on to the end of list1.
          
   length(list)
          return the length of the list.
          
   nth(i, list)
          return the i'th element in list.
          
   lconsi, ...
          There are integer versions of these: lconsi, lappendi, nthi.
          List's containing integers instead of Node pointers are used to
          hold list of relation object id's and other integer quantities.
          
   You can print nodes easily inside gdb. First, to disable output
   truncation when you use the gdb print command:
(gdb) set print elements 0

   Instead of printing values in gdb format, you can use the next two
   commands to print out List, Node, and structure contents in a verbose
   format that is easier to understand. List's are unrolled into nodes,
   and nodes are printed in detail. The first prints in a short format,
   and the second in a long format:
(gdb) call print(any_pointer)
    (gdb) call pprint(any_pointer)

   The output appears in the postmaster log file, or on your screen if
   you are running a backend directly without a postmaster.
   
  5) How do I add a feature or fix a bug?
  
   The source code is over 250,000 lines. Many problems/features are
   isolated to one specific area of the code. Others require knowledge of
   much of the source. If you are confused about where to start, ask the
   hackers list, and they will be glad to assess the complexity and give
   pointers on where to start.
   
   Another thing to keep in mind is that many fixes and features can be
   added with surprisingly little code. I often start by adding code,
   then looking at other areas in the code where similar things are done,
   and by the time I am finished, the patch is quite small and compact.
   
   When adding code, keep in mind that it should use the existing
   facilities in the source, for performance reasons and for simplicity.
   Often a review of existing code doing similar things is helpful.
   
  6) How do I download/update the current source tree?
  
   There are several ways to obtain the source tree. Occasional
   developers can just get the most recent source tree snapshot from
   ftp.postgresql.org. For regular developers, you can use CVS. CVS
   allows you to download the source tree, then occasionally update your
   copy of the source tree with any new changes. Using CVS, you don't
   have to download the entire source each time, only the changed files.
   Anonymous CVS does not allows developers to update the remote source
   tree, though privileged developers can do this. There is a CVS FAQ on
   our web site that describes how to use remote CVS. You can also use
   CVSup, which has similarly functionality, and is available from
   ftp.postgresql.org.
   
   To update the source tree, there are two ways. You can generate a
   patch against your current source tree, perhaps using the make_diff
   tools mentioned above, and send them to the patches list. They will be
   reviewed, and applied in a timely manner. If the patch is major, and
   we are in beta testing, the developers may wait for the final release
   before applying your patches.
   
   For hard-core developers, Marc(scrappy@@postgresql.org) will give you a
   Unix shell account on postgresql.org, so you can use CVS to update the
   main source tree, or you can ftp your files into your account, patch,
   and cvs install the changes directly into the source tree.
   
  6) How do I test my changes?
  
   First, use psql to make sure it is working as you expect. Then run
   src/test/regress and get the output of src/test/regress/checkresults
   with and without your changes, to see that your patch does not change
   the regression test in unexpected ways. This practice has saved me
   many times. The regression tests test the code in ways I would never
   do, and has caught many bugs in my patches. By finding the problems
   now, you save yourself a lot of debugging later when things are
   broken, and you can't figure out when it happened.
   
  7) I just added a field to a structure. What else should I do?
  
   The structures passing around from the parser, rewrite, optimizer, and
   executor require quite a bit of support. Most structures have support
   routines in src/backend/nodes used to create, copy, read, and output
   those structures. Make sure you add support for your new field to
   these files. Find any other places the structure may need code for
   your new field. mkid is helpful with this (see above).
   
  8) Why are table, column, type, function, view names sometimes referenced as
  Name or NameData, and sometimes as char *?
  
   Table, column, type, function, and view names are stored in system
   tables in columns of type Name. Name is a fixed-length,
   null-terminated type of NAMEDATALEN bytes. (The default value for
   NAMEDATALEN is 32 bytes.)
typedef struct nameData
    {
        char        data[NAMEDATALEN];
    } NameData;
    typedef NameData *Name;

   Table, column, type, function, and view names that come into the
   backend via user queries are stored as variable-length,
   null-terminated character strings.
   
   Many functions are called with both types of names, ie. heap_open().
   Because the Name type is null-terminated, it is safe to pass it to a
   function expecting a char *. Because there are many cases where
   on-disk names(Name) are compared to user-supplied names(char *), there
   are many cases where Name and char * are used interchangeably.
   
  9) How do I efficiently access information in tables from the backend code?
  
   You first need to find the tuples(rows) you are interested in. There
   are two ways. First, SearchSysCache() and related functions allow you
   to query the system catalogs. This is the preferred way to access
   system tables, because the first call to the cache loads the needed
   rows, and future requests can return the results without accessing the
   base table. The caches use system table indexes to look up tuples. A
   list of available caches is located in
   src/backend/utils/cache/syscache.c.
   src/backend/utils/cache/lsyscache.c contains many column-specific
   cache lookup functions.
   
   The rows returned are cache-owned versions of the heap rows.
   Therefore, you must not modify or delete the tuple returned by
   SearchSysCache(). What you should do is release it with
   ReleaseSysCache() when you are done using it; this informs the cache
   that it can discard that tuple if necessary. If you neglect to call
   ReleaseSysCache(), then the cache entry will remain locked in the
   cache until end of transaction, which is tolerable but not very
   desirable.
   
   If you can't use the system cache, you will need to retrieve the data
   directly from the heap table, using the buffer cache that is shared by
   all backends. The backend automatically takes care of loading the rows
   into the buffer cache.
   
   Open the table with heap_open(). You can then start a table scan with
   heap_beginscan(), then use heap_getnext() and continue as long as
   HeapTupleIsValid() returns true. Then do a heap_endscan(). Keys can be
   assigned to the scan. No indexes are used, so all rows are going to be
   compared to the keys, and only the valid rows returned.
   
   You can also use heap_fetch() to fetch rows by block number/offset.
   While scans automatically lock/unlock rows from the buffer cache, with
   heap_fetch(), you must pass a Buffer pointer, and ReleaseBuffer() it
   when completed.
   
   Once you have the row, you can get data that is common to all tuples,
   like t_self and t_oid, by merely accessing the HeapTuple structure
   entries. If you need a table-specific column, you should take the
   HeapTuple pointer, and use the GETSTRUCT() macro to access the
   table-specific start of the tuple. You then cast the pointer as a
   Form_pg_proc pointer if you are accessing the pg_proc table, or
   Form_pg_type if you are accessing pg_type. You can then access the
   columns by using a structure pointer:
((Form_pg_class) GETSTRUCT(tuple))->relnatts

   You must not directly change live tuples in this way. The best way is
   to use heap_modifytuple() and pass it your original tuple, and the
   values you want changed. It returns a palloc'ed tuple, which you pass
   to heap_replace(). You can delete tuples by passing the tuple's t_self
   to heap_destroy(). You use t_self for heap_update() too. Remember,
   tuples can be either system cache copies, which may go away after you
   call ReleaseSysCache(), or read directly from disk buffers, which go
   away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
   heap_fetch() case. Or it may be a palloc'ed tuple, that you must
   pfree() when finished.
   
  10) What is elog()?
d261 7
a267 8
   elog() is used to send messages to the front-end, and optionally
   terminate the current query being processed. The first parameter is an
   elog level of NOTICE, DEBUG, ERROR, or FATAL. NOTICE prints on the
   user's terminal and the postmaster logs. DEBUG prints only in the
   postmaster logs. ERROR prints in both places, and terminates the
   current query, never returning from the call. FATAL terminates the
   backend process. The remaining parameters of elog are a printf-style
   set of parameters to print.
d269 1
a269 1
  11) What is configure all about?
d291 1
a291 1
  12) How do I add a new port?
d308 1
a308 13
  13) What is CommandCounterIncrement()?
  
   Normally, transactions can not see the rows they modify. This allows
   UPDATE foo SET x = x + 1 to work correctly.
   
   However, there are cases where a transactions needs to see rows
   affected in previous parts of the transaction. This is accomplished
   using a Command Counter. Incrementing the counter allows transactions
   to be broken into pieces so each piece can see rows modified by
   previous pieces. CommandCounterIncrement() increments the Command
   Counter, creating a new part of the transaction.
   
  14) Why don't we use threads in the backend?
d317 1
a317 1
  15) How are RPM's packaged?
d412 1
a412 1
  16) How are CVS branches managed?
d471 63
a533 1
  17) How go I get involved in PostgreSQL development?
d535 13
a547 1
   This was written by Lamar Owen:
d549 5
a553 2
   2001-06-22
   What open source development process is used by the PostgreSQL team?
d555 6
a560 6
   Read HACKERS for six months (or a full release cycle, whichever is
   longer). Really. HACKERS _is_the process. The process is not well
   documented (AFAIK -- it may be somewhere that I am not aware of) --
   and it changes continually.
   What development environment (OS, system, compilers, etc) is required
   to develop code?
d562 1
a562 7
   Developers Corner on the website has links to this information. The
   distribution tarball itself includes all the extra tools and documents
   that go beyond a good Unix-like development environment. In general, a
   modern unix with a modern gcc, GNU make or equivalent, autoconf (of a
   particular version), and good working knowledge of those tools are
   required.
   What areas need support?
d564 57
a620 1
   The TODO list.
d622 8
a629 6
   You've made the first step, by finding and subscribing to HACKERS.
   Once you find an area to look at in the TODO, and have read the
   documentation on the internals, etc, then you check out a current
   CVS,write what you are going to write (keeping your CVS checkout up to
   date in the process), and make up a patch (as a context diff only) and
   send to the PATCHES list, prefereably.
d631 8
a638 7
   Discussion on the patch typically happens here. If the patch adds a
   major feature, it would be a good idea to talk about it first on the
   HACKERS list, in order to increase the chances of it being accepted,
   as well as toavoid duplication of effort. Note that experienced
   developers with a proven track record usually get the big jobs -- for
   more than one reason. Also note that PostgreSQL is highly portable --
   nonportable code will likely be dismissed out of hand.
d640 10
a649 5
   Once your contributions get accepted, things move from there.
   Typically, you would be added as a developer on the list on the
   website when one of the other developers recommends it. Membership on
   the steering committee is by invitation only, by the other steering
   committee members, from what I have gathered watching froma distance.
d651 4
a654 2
   I make these statements from having watched the process for over two
   years.
d656 6
a661 7
   To see a good example of how one goes about this, search the archives
   for the name 'Tom Lane' and see what his first post consisted of, and
   where he took things. In particular, note that this hasn't been _that_
   long ago -- and his bugfixing and general deep knowledge with this
   codebase is legendary. Take a few days to read after him. And pay
   special attention to both the sheer quantity as well as the
   painstaking quality of his work. Both are in high demand.
@


1.29
log
@Update FAQ_DEV.
@
text
@d605 1
a606 2
  What open source development process is used by the PostgreSQL team?
  
d611 2
a613 3
  What development environment (OS, system, compilers, etc) is required to
  develop code?
  
d620 1
a621 2
  What area or two needs some support?
  
@


1.28
log
@Update FAQ_DEV.
@
text
@d458 4
a461 4
    2. 2.) The initscript;
    3. 3.) Any other ancilliary scripts and files;
    4. 4.) A README.rpm-dist document that tries to adequately document
       both the differences between the RPM build and the WHY of the
d465 2
a466 2
    5. 5.) The spec file that throws it all together. This is not a
       trivial undertaking in a package of this size.
@


1.27
log
@Update FAQ_DEV.
@
text
@d456 12
a467 16
   
   1.) A set of patches to make certain portions of the source tree
   'behave' in the different environment of the RPMset;
   
   2.) The initscript;
   
   3.) Any other ancilliary scripts and files;
   
   4.) A README.rpm-dist document that tries to adequately document both
   the differences between the RPM build and the WHY of the differences,
   as well as useful RPM environment operations (like, using syslog,
   upgrading, getting postmaster to start at OS boot, etc);
   
   5.) The spec file that throws it all together. This is not a trivial
   undertaking in a package of this size.
   
@


1.26
log
@Update FAQ_DEV.
@
text
@d610 2
a611 7
   > If someone was interested in joining the development team, where
   would
   > they...
   > - Find a description of the open source development process used by
   the
   > PostgreSQL team.
   
d617 3
a619 3
   > - Find the development environment (OS, system, compilers, etc)
   > required to develop code.
   
d627 2
a628 2
   > - Find an area or two that needs some support.
   
@


1.25
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Dec 4 01:14:35 EST 2001
d449 96
a544 89
2001-05-03

As to how the RPMs are built -- to answer that question sanely requires
me to know how much experience you have with the whole RPM paradigm.
'How is the RPM built?' is a multifaceted question.  The obvious simple
answer is that I maintain:
    1.) A set of patches to make certain portions of the source
        tree 'behave' in the different environment of the RPMset;
    2.) The initscript;
    3.) Any other ancilliary scripts and files;
    4.) A README.rpm-dist document that tries to adequately document
        both the differences between the RPM build and the WHY of the
        differences, as well as useful RPM environment operations
        (like, using syslog, upgrading, getting postmaster to
        start at OS boot, etc);
    5.) The spec file that throws it all together.  This is not a
        trivial undertaking in a package of this size.

I then download and build on as many different canonical distributions
as I can -- currently I am able to build on Red Hat 6.2, 7.0, and 7.1 on
my personal hardware.  Occasionally I receive opportunity from certain
commercial enterprises such as Great Bridge and PostgreSQL, Inc. to
build on other distributions.

I test the build by installing the resulting packages and running the
regression tests.  Once the build passes these tests, I upload to the
postgresql.org ftp server and make a release announcement.  I am also
responsible for maintaining the RPM download area on the ftp site.

You'll notice I said 'canonical' distributions above.  That simply means
that the machine is as stock 'out of the box' as practical -- that is,
everything (except select few programs) on these boxen are installed by
RPM; only official Red Hat released RPMs are used (except in unusual
circumstances involving software that will not alter the build -- for
example, installing a newer non-RedHat version of the Dia diagramming
package is OK -- installing Python 2.1 on the box that has Python 1.5.2
installed is not, as that alters the PostgreSQL build).  The RPM as
uploaded is built to as close to out-of-the-box pristine as is
possible.  Only the standard released 'official to that release'
compiler is used -- and only the standard official kernel is used as
well.

For a time I built on Mandrake for RedHat consumption -- no more.
Nonstandard RPM building systems are worse than useless.  Which is not
to say that Mandrake is useless!  By no means is Mandrake useless --
unless you are building Red Hat RPMs -- and Red Hat is useless if you're
trying to build Mandrake or SuSE RPMs, for that matter.  But I would be
foolish to use 'Lamar Owen's Super Special RPM Blend Distro 0.1.2' to
build for public consumption! :-)

I _do_ attempt to make the _source_ RPM compatible with as many
distributions as possible -- however, since I have limited resources (as
a volunteer RPM maintainer) I am limited as to the amount of testing
said build will get on other distributions, architectures, or systems.

And, while I understand people's desire to immediately upgrade to the
newest version, realize that I do this as a side interest -- I have a
regular, full-time job as a broadcast
engineer/webmaster/sysadmin/Technical Director which occasionally
prevents me from making timely RPM releases. This happened during the
early part of the 7.1 beta cycle -- but I believe I was pretty much on
the ball for the Release Candidates and the final release.

I am working towards a more open RPM distribution -- I would dearly love
to more fully document the process and put everything into CVS -- once I
figure out how I want to represent things such as the spec file in a CVS
form.  It makes no sense to maintain a changelog, for instance, in the
spec file in CVS when CVS does a better job of changelogs -- I will need
to write a tool to generate a real spec file from a CVS spec-source file
that would add version numbers, changelog entries, etc to the result
before building the RPM.  IOW, I need to rethink the process -- and then
go through the motions of putting my long RPM history into CVS one
version at a time so that version history information isn't lost.

As to why all these files aren't part of the source tree, well, unless
there was a large cry for it to happen, I don't believe it should.
PostgreSQL is very platform-agnostic -- and I like that.  Including the
RPM stuff as part of the Official Tarball (TM) would, IMHO, slant that
agnostic stance in a negative way.  But maybe I'm too sensitive to
that.  I'm not opposed to doing that if that is the consensus of the
core group -- and that would be a sneaky way to get the stuff into CVS
:-).  But if the core group isn't thrilled with the idea (and my
instinct says they're not likely to be), I am opposed to the idea -- not
to keep the stuff to myself, but to not hinder the platform-neutral
stance. IMHO, of course.

Of course, there are many projects that DO include all the files
necessary to build RPMs from their Official Tarball (TM).

d548 16
a563 16
2001-05-07

If you just do basic "cvs checkout", "cvs update", "cvs commit", then
you'll always be dealing with the HEAD version of the files in CVS.
That's what you want for development, but if you need to patch past
stable releases then you have to be able to access and update the
"branch" portions of our CVS repository.  We normally fork off a branch
for a stable release just before starting the development cycle for the
next release.

The first thing you have to know is the branch name for the branch you
are interested in getting at.  To do this, look at some long-lived file,
say the top-level HISTORY file, with "cvs status -v" to see what the
branch names are.  (Thanks to Ian Lance Taylor for pointing out that
this is the easiest way to do it.)  Typical branch names are:

d568 11
a578 11
OK, so how do you do work on a branch?  By far the best way is to create
a separate checkout tree for the branch and do your work in that.  Not
only is that the easiest way to deal with CVS, but you really need to
have the whole past tree available anyway to test your work.  (And you
*better* test your work.  Never forget that dot-releases tend to go out
with very little beta testing --- so whenever you commit an update to a
stable branch, you'd better be doubly sure that it's correct.)

Normally, to checkout the head branch, you just cd to the place you
want to contain the toplevel "pgsql" directory and say

d581 1
a581 2
To get a past branch, you cd to whereever you want it and say

d584 1
a584 2
For example, just a couple days ago I did

d589 15
a603 15
and now I have a maintenance copy of 7.1.*.

When you've done a checkout in this way, the branch name is "sticky":
CVS automatically knows that this directory tree is for the branch,
and whenever you do "cvs update" or "cvs commit" in this tree, you'll
fetch or store the latest version in the branch, not the head version.
Easy as can be.

So, if you have a patch that needs to apply to both the head and a
recent stable branch, you have to make the edits and do the commit
twice, once in your development tree and once in your stable branch
tree.  This is kind of a pain, which is why we don't normally fork
the tree right away after a major release --- we wait for a dot-release
or two, so that we won't have to double-patch the first wave of fixes.

d607 60
a666 54
2001-06-22

> If someone was interested in joining the development team, where would
> they...
> -  Find a description of the open source development process used by the
> PostgreSQL team.

Read HACKERS for six months (or a full release cycle, whichever is longer).
Really.  HACKERS _is_the process.  The process is not well documented (AFAIK
-- it may be somewhere that I am not aware of) -- and it changes continually.

> -  Find the development environment (OS, system, compilers, etc)
> required to develop code.

Developers Corner on the website
has links to this information.  The  distribution tarball itself
includes all the extra tools and documents that  go beyond a good
Unix-like development environment.  In general, a modern  unix with a
modern gcc, GNU make or equivalent, autoconf (of a particular  version),
and good working knowledge of those tools are required.

> -  Find an area or two that needs some support.

The TODO list.

You've made the first step, by finding and subscribing to HACKERS.  Once you
find an area to look at in the TODO, and have read the documentation on the
internals, etc, then you check out a current CVS,write what you are going to
write (keeping your CVS checkout up to date in the process), and make up a
patch (as a context diff only) and send to the PATCHES list, prefereably.

Discussion on the patch typically happens here.  If the patch adds a major
feature, it would be a good idea to talk about it first on the HACKERS list,
in order to increase the chances of it being accepted, as well as toavoid
duplication of effort.  Note that experienced developers with a proven track
record usually get the big jobs -- for more than one reason.  Also note that
PostgreSQL is highly portable -- nonportable code will likely be dismissed
out of  hand.

Once your contributions get accepted, things move from there. Typically, you
would be added as a developer on the list on the website when one of the
other developers recommends it.  Membership on the steering committee is by
invitation only, by the other steering committee members, from what I have
gathered watching froma distance.

I make these statements from having watched the process for over two years.

To see a good example of how one goes about this, search the archives for the
name 'Tom Lane' and see what his first post consisted of, and where he took
things.  In particular, note that this hasn't been _that_ long ago -- and his
bugfixing and general deep knowledge with this codebase is legendary.  Take a
few days to read after him.  And pay special attention to both the sheer
quantity as well as the painstaking quality of his work.  Both are in high
demand.
@


1.24
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Dec 4 01:13:55 EST 2001
d9 1
a9 1
   postgreSQL Web site, http://www.postgresql.org.
@


1.23
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 27 20:38:34 EST 2001
d9 1
a9 1
   postgreSQL Web site, http://PostgreSQL.org.
@


1.22
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 27 20:20:21 EST 2001
@


1.21
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 27 19:36:27 EST 2001
d449 2
a450 1
Thu, 03 May 2001 21:22:05 -0400
d541 2
a542 1
Mon, 07 May 2001 19:35:03 -0400
d602 2
a603 1
Fri, 22 Jun 2001 12:59:03 -0400
@


1.20
log
@Manual update.
@
text
@d4 1
a4 1
   Last updated: Tue Nov 27 19:09:59 EST 2001
d449 1
d540 1
d600 1
@


1.19
log
@Chinese PO patch

Laser.
@
text
@d4 1
a4 1
   Last updated: Mon Nov 26 21:48:19 EST 2001
d468 2
a469 2
commercial enterprises such as Great Bridge and PostgreSQL Inc to build
on other distributions.
d548 5
a552 38
are interested in getting at.  Unfortunately Marc has been less than
100% consistent in naming the things.  One way to check is to apply
"cvs log" to any file that goes back a long time, for example HISTORY
in the top directory:

$ cvs log HISTORY | more

RCS file: /home/projects/pgsql/cvsroot/pgsql/HISTORY,v
Working file: HISTORY
head: 1.106
branch:
locks: strict
access list:
symbolic names:
        REL7_1_STABLE: 1.106.0.2
        REL7_1_BETA: 1.79
        REL7_1_BETA3: 1.86
        REL7_1_BETA2: 1.86
        REL7_1: 1.102
        REL7_0_PATCHES: 1.70.0.2
        REL7_0: 1.70
        REL6_5_PATCHES: 1.52.0.2
        REL6_5: 1.52
        REL6_4: 1.44.0.2
        release-6-3: 1.33
        SUPPORT: 1.1.1.1
        PG95-DIST: 1.1.1
keyword substitution: kv
total revisions: 129;   selected revisions: 129
More---q

Unfortunately "cvs log" isn't all that great about distinguishing
branches from tags --- it calls 'em all "symbolic names".  (A "tag" just
marks a specific timepoint across all files --- it's essentially a
snapshot whereas a branch is a changeable fileset.)  Rule of thumb is
that names attached to four-number versions where the third number is
zero represent branches, the others are just tags.  Here we can see that
the extant branches are
a555 4
The next commit to the head will be revision 1.107, whereas any changes
committed into the REL7_1_STABLE branch will have revision numbers like
1.106.2.*, corresponding to the branch number 1.106.0.2 (don't ask where
the zero went...).
a594 3
   Also, Ian Lance Taylor points out that branches and tags can be
   distiguished by using "cvs status -v".
   
d610 6
a615 5
Developers Corner on the website has links to this information.  The
distribution tarball itself includes all the extra tools and documents that
go beyond a good Unix-like development environment.  In general, a modern
unix with a modern gcc, GNU make or equivalent, autoconf (of a particular
version), and good working knowledge of those tools are required.
@


1.18
log
@Update FAQ_DEV.
@
text
@d4 1
a4 1
   Last updated: Fri Jun 9 21:54:54 EDT 2000
d33 1
d448 1
a448 1
   This is from Lamar Owen:
d453 11
a463 11
        1.)     A set of patches to make certain portions of the source
                tree 'behave' in the different environment of the RPMset;
        2.)     The initscript;
        3.)     Any other ancilliary scripts and files;
        4.)     A README.rpm-dist document that tries to adequately document
                both the differences between the RPM build and the WHY of the
                differences, as well as useful RPM environment operations
                (like, using syslog, upgrading, getting postmaster to
                start at OS boot, etc);
        5.)     The spec file that throws it all together.  This is not a
                trivial undertaking in a package of this size.
d586 3
a588 3
        REL7_1_STABLE
        REL7_0_PATCHES
        REL6_5_PATCHES
d605 1
a605 1
        cvs ... checkout pgsql
d609 1
a609 1
        cvs ... checkout -r BRANCHNAME pgsql
d613 3
a615 3
        mkdir ~postgres/REL7_1
        cd ~postgres/REL7_1
        cvs ... checkout -r REL7_1_STABLE pgsql
d634 55
@


1.17
log
@Rename make_keywords.README to make_keywords.
@
text
@d32 1
d40 2
a41 2
    RELEASE_CHANGES     changes we have to make for each release
    SQL_keywords        standard SQL'92 keywords
d46 1
a46 1
    find_typedef    finds a list of typedefs in the source code
d51 1
a51 1
    make_keywords.README    make comparison of our keywords and SQL'92
d534 99
@


1.16
log
@Update FAQ_DEV.
@
text
@d31 1
d45 2
a46 1
    find_typedef        get a list of typedefs in the source code
d54 1
d133 5
a137 2
   not be reformatted in any way. pginclude contains scripts used to add
   needed #include's to include files, and removed unneeded #include's.
d443 90
@


1.15
log
@Update FAQ_DEV.
@
text
@d83 2
a84 1
   the distribution.
@


1.14
log
@Update FAQ_DEV.
@
text
@d30 1
a30 1
   13) Why don't we use threads in the backend?
@


1.13
log
@Change SearchSysCache coding conventions so that a reference count is
maintained for each cache entry.  A cache entry will not be freed until
the matching ReleaseSysCache call has been executed.  This eliminates
worries about cache entries getting dropped while still in use.  See
my posting to pg-hackers of even date for more info.
@
text
@d30 1
d38 16
a53 17
        RELEASE_CHANGES         changes we have to make for each release
        SQL_keywords            standard SQL'92 keywords
        backend                 description/flowchart of the backend directorie
s
        ccsym                   find standard defines made by your compiler
        entab                   converts tabs to spaces, used by pgindent
        find_static             finds functions that could be made static
        find_typedef            get a list of typedefs in the source code
        make_ctags              make vi 'tags' file in each directory
        make_diff               make *.orig and diffs of source
        make_etags              make emacs 'etags' files
        make_keywords.README    make comparison of our keywords and SQL'92
        make_mkid               make mkid ID files
        mkldexport              create AIX exports file
        pgindent                indents C source files
        pginclude               scripts for adding/removing include files
        unused_oids             in pgsql/src/include/catalog
d74 3
a76 3
        ftp://alpha.gnu.org/gnu/id-utils-3.2d.tar.gz
        ftp://tug.org/gnu/id-utils-3.2d.tar.gz
        ftp://ftp.enst.fr/pub/gnu/gnits/id-utils-3.2d.tar.gz
d88 11
a98 11
        vi in ~/.exrc:
                        set tabstop=4
                set sw=4
        more:
                more -x4
        less:
                less -x4
        emacs:
                M-x set-variable tab-width
            or
                ; Cmd to set tab stops &etc for working with PostgreSQL code
d100 1
a100 1
                                  '("bsd"
d104 1
a104 1
                                             (c-offsets-alist .
d108 1
a108 1
            and add this to your autoload list (modify file path in macro):
d110 11
a120 12
                (setq auto-mode-alist
                      (cons '("\\`/usr/local/src/pgsql/.*\\.[chyl]\\'" . pgsql-
c-mode)
                        auto-mode-alist))
            or
                /*
                 * Local variables:
                 *  tab-width: 4
                 *  c-indent-level: 4
                 *  c-basic-offset: 4
                 * End:
                 */
d176 1
a176 2

    List *i, *list;
d208 1
a208 2

        (gdb) set print elements 0
d215 2
a216 3

        (gdb) call print(any_pointer)
        (gdb) call pprint(any_pointer)
d291 5
a295 5
        typedef struct nameData
        {
            char        data[NAMEDATALEN];
        } NameData;
        typedef NameData *Name;
d310 2
a311 2
   are two ways. First, SearchSysCache() and related functions allow
   you to query the system catalogs. This is the preferred way to access
d320 8
a327 7
   The rows returned are cache-owned versions of the heap rows.  Therefore,
   you must not modify or delete the tuple returned by SearchSysCache().
   What you *should* do is release it with ReleaseSysCache() when you are
   done using it; this informs the cache that it can discard that tuple
   if necessary.  If you neglect to call ReleaseSysCache(), then the cache
   entry will remain locked in the cache until end of transaction, which is
   tolerable but not very desirable.
d344 20
a363 22

   Once you have the row, you can get data that is common
   to all tuples, like t_self and t_oid, by merely accessing the
   HeapTuple structure entries. If you need a table-specific column, you
   should take the HeapTuple pointer, and use the GETSTRUCT() macro to
   access the table-specific start of the tuple. You then cast the
   pointer as a Form_pg_proc pointer if you are accessing the pg_proc
   table, or Form_pg_type if you are accessing pg_type. You can then
   access the columns by using a structure pointer:

        ((Form_pg_class) GETSTRUCT(tuple))->relnatts

   You must not directly change live tuples in this way. The best way
   is to use heap_modifytuple() and pass it your original tuple, and the
   values you want changed. It returns a palloc'ed tuple, which you
   pass to heap_replace(). You can delete tuples by passing the tuple's
   t_self to heap_destroy(). You use t_self for heap_update() too.

   Remember, tuples can be either system cache copies, which may go away
   after you call ReleaseSysCache(), or read directly from disk buffers,
   which go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(),
   in the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
d427 9
@


1.12
log
@Update FAQ_DEV.
@
text
@d314 1
a314 1
   are two ways. First, SearchSysCacheTuple() and related functions allow
d324 7
a330 8
   The rows returned are cached-owned versions of the heap rows. They are
   invalidated when the base table changes. Because the cache is local to
   each backend, you may use the pointer returned from the cache for
   short periods without making a copy of the tuple. If you send the
   pointer into a large function that will be doing its own cache
   lookups, it is possible the cache entry may be flushed, so you should
   use SearchSysCacheTupleCopy() in these cases, and pfree() the tuple
   when you are done.
d346 3
a348 1
   when completed. Once you have the row, you can get data that is common
d359 3
a361 3
   You should not directly change live tuples in this way. The best way
   is to use heap_tuplemodify() and pass it your palloc'ed tuple, and the
   values you want changed. It returns another palloc'ed tuple, which you
d363 6
a368 5
   t_self to heap_destroy(). You can use it for heap_update() too.
   Remember, tuples can be either system cache versions, which may go
   away soon after you get them, buffer cache versions, which go away
   when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
   heap_fetch() case. Or it may be a palloc'ed tuple, that you must
@


1.11
log
@Update FAQ_DEV.
@
text
@d429 1
a429 1
   Counter, creating a new piece of the transaction.
@


1.10
log
@update developers faq
@
text
@d29 1
d418 12
@


1.9
log
@UPdate developers faq
@
text
@d72 8
a79 3
   Third, you need to get mkid from ftp.postgresql.org. By running
   tools/make_mkid, an archive of source symbols can be created that can
   be rapidly queried like grep or edited. Others prefer glimpse.
@


1.8
log
@Inheritance overhaul by  Chris Bitmead <chris@@bitmead.com>
@
text
@d4 1
a4 1
   Last updated: Fri Dec 24 11:43:42 EST 1999
d94 1
a94 1
			          '("bsd"
d98 1
a98 1
			                     (c-offsets-alist .
d312 2
a313 2
   base table. Some of the caches use system table indexes to look up
   tuples. A list of available caches is located in
d356 6
a361 5
   t_self to heap_destroy(). Remember, tuples can be either system cache
   versions, which may go away soon after you get them, buffer cache
   version, which will go away when you heap_getnext(), heap_endscan, or
   ReleaseBuffer(), in the heap_fetch() case. Or it may be a palloc'ed
   tuple, that you must pfree() when finished.
@


1.7
log
@Update developers faq.
@
text
@d93 8
a100 10
                (defun pgsql-mode ()
                  "Set PostgreSQL C indenting conventions in current buffer."
                  (interactive)
                  (c-mode)                            ; necessary to make c-set
-offset local!
                  (setq tab-width 4)                  ; already buffer-local
                  ; (setq comment-column 48)          ; already buffer-local
                  (c-set-style "bsd")
                  (c-set-offset 'case-label '+)
                )
@


1.7.2.1
log
@update developers faq
@
text
@d4 1
a4 1
   Last updated: Fri Jun 9 21:54:54 EDT 2000
d72 3
a74 8
   Third, you need to get id-utils from:
        ftp://alpha.gnu.org/gnu/id-utils-3.2d.tar.gz
        ftp://tug.org/gnu/id-utils-3.2d.tar.gz
        ftp://ftp.enst.fr/pub/gnu/gnits/id-utils-3.2d.tar.gz

   By running tools/make_mkid, an archive of source symbols can be
   created that can be rapidly queried like grep or edited. Others prefer
   glimpse.
d93 10
a102 8
             (c-add-style "pgsql"
                                  '("bsd"
                                 (indent-tabs-mode . t)
                                 (c-basic-offset   . 4)
                                 (tab-width . 4)
                                             (c-offsets-alist .
                                            ((case-label . +))))
                       t) ; t = set this mode on
d314 2
a315 2
   base table. The caches use system table indexes to look up tuples. A
   list of available caches is located in
d358 5
a362 6
   t_self to heap_destroy(). You can use it for heap_update() too.
   Remember, tuples can be either system cache versions, which may go
   away soon after you get them, buffer cache versions, which go away
   when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
   heap_fetch() case. Or it may be a palloc'ed tuple, that you must
   pfree() when finished.
@


1.6
log
@Update developers faq in main tree.
@
text
@d4 1
a4 1
   Last updated: Tue Dec 21 12:30:20 EST 1999
d103 7
@


1.5
log
@Update stuff for 6.5.1 release.
@
text
@d4 1
a4 1
   Last updated: Sat Jul 10 00:38:09 EDT 1999
d6 1
a6 1
   Current maintainer: Bruce Momjian (maillist@@candle.pha.pa.us)
d51 2
d79 35
a113 3
   pgindent will format source files to match our standard format, which
   has four-space tabs, and an indenting format specified by flags to the
   your operating system's utility indent.
d119 5
a123 1
   not be reformatted in any way.
d403 3
a405 2
   src/include/storage/s_lock.h for your CPU. There is a backend/port
   directory if you need special files for your OS.
@


1.5.2.1
log
@Update for 6.5.2.
@
text
@a50 1
        pginclude               scripts for adding/removing include files
d85 1
a85 2
   not be reformatted in any way. pginclude contains scripts used to add
   needed #include's to include files, and removed unneeded #include's.
d365 2
a366 3
   src/include/storage/s_lock.h for your CPU. There is also a
   src/makefiles directory for port-specific Makefile handling. There is
   a backend/port directory if you need special files for your OS.
@


1.4
log
@Update FAQ's for release.
@
text
@d4 1
a4 1
   Last updated: Mon Feb 22 17:15:06 EST 1999
d9 1
a9 1
   postgreSQL Web site, http://postgreSQL.org.
d27 2
d299 1
a299 1
   to all tuples, like t_self and t_oid, by mererly accessing the
d329 38
@


1.3
log
@HISTORY file update.
@
text
@d4 1
a4 1
   Last updated: Fri Oct 2 15:21:32 EDT 1998
d70 1
a70 1
   be rapidly queried like grep or edited.
d108 2
a109 3
   specifies what type of data is inside the Node. Lists are lists of
   Nodes. lfirst(), lnext(), and foreach() are used to get, skip, and
   traverse through Lists.
d111 46
d158 1
a158 1
   truncation:
d162 5
a166 3
   You may then use either of the next two commands to print out List,
   Node, and structure contents. The first prints in a short format, and
   the second in a long format:
d171 3
d250 1
a250 1
   Table, column, type, function, and view names that come in to the
d297 1
a297 1
   to all tuples, like t_ctid and t_oid, by mererly accessing the
d302 1
a302 1
   table, or TypeTupleForm if you are accessing pg_type. You can then
d311 1
a311 1
   t_ctid to heap_destroy(). Remember, tuples can be either system cache
@


1.3.2.1
log
@Prepare for 6.4.1.
@
text
@d200 1
a200 1
   Table, column, type, function, and view names that come into the
d252 1
a252 1
   table, or Form_pg_type if you are accessing pg_type. You can then
@


1.2
log
@Add FAQ_CVS.
@
text
@a0 28
Developer's Frequently Asked Questions (FAQ) for PostgreSQL

Last updated: Wed Feb 11 20:23:01 EST 1998

Current maintainer: Bruce Momjian (maillist@@candle.pha.pa.us)

The most recent version of this document can be viewed at the postgreSQL Web
site, http://postgreSQL.org.

  ------------------------------------------------------------------------

Questions answered:

1) What tools are available for developers?
2) What books are good for developers?
3) Why do we use palloc() and pfree() to allocate memory?
4) Why do we use Node and List to make data structures?
5) How do I add a feature or fix a bug?
6) How do I download/update the current source tree?
7) How do I test my changes?

  ------------------------------------------------------------------------

1) What tools are available for developers?

Aside from the User documentation mentioned in the regular FAQ, there
are several development tools available. First, all the files in the
pgsql/src/tools directory are designed for developers.
d2 32
d36 2
a37 1
        backend                 web flowchart of the backend directories
d50 227
a276 101
Let me note some of these. If you point your browser at the
pgsql/src/tools/backend directory, you will see all the backend
components in a flow chart. You can click on any one to see a
description. If you then click on the directory name, you will be taken
to the source directory, to browse the actual source code behind it. We
also have several README files in some source directories to describe
the function of the module. The browser will display these when you
enter the directory also. The pgsql/src/tools/backend directory is also
contained on our web page under the title Backend Flowchart.

Second, you really should have an editor that can handle tags, so you can
tag a function call to see the function definition, and then tag inside that
function to see an even lower-level function, and then back out twice to
return to the original function. Most editors support this via tags or etags
files.

Third, you need to get mkid from ftp.postgresql.org. By running
tools/make_mkid, an archive of source symbols can be created that can be
rapidly queried like grep or edited.

make_diff has tools to create patch diff files that can be applied to the
distribution.

pgindent will format source files to match our standard format, which has
four-space tabs, and an indenting format specified by flags to the your
operating system's utility indent.

2) What books are good for developers?

I have three good books, An Introduction to Database Systems, by C.J. Date,
Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et. al,
Addison, Wesley, and Transaction Processing:  Concepts and Techniques,
by Jim Gray and Andreas Reuter, Morgan, Kaufmann.

3) Why do we use palloc() and pfree() to allocate memory?

palloc() and pfree() are used in place of malloc() and free() because we
automatically free all memory allocated when a transaction completes. This
makes it easier to make sure we free memory that gets allocated in one
place, but only freed much later. There are several contexts that memory can
be allocated in, and this controls when the allocated memory is
automatically freed by the backend.

4) Why do we use Node and List to make data structures?

We do this because this allows a consistent way to pass data inside the
backend in a flexible way. Every node has a NodeTag which specifies what
type of data is inside the Node. Lists are lists of Nodes. lfirst(),
lnext(), and foreach() are used to get, skip, and traverse through Lists.

5) How do I add a feature or fix a bug?

The source code is over 250,000 lines. Many problems/features are isolated
to one specific area of the code. Others require knowledge of much of the
source. If you are confused about where to start, ask the hackers list, and
they will be glad to assess the complexity and give pointers on where to
start.

Another thing to keep in mind is that many fixes and features can be added
with surprisingly little code. I often start by adding code, then looking at
other areas in the code where similar things are done, and by the time I am
finished, the patch is quite small and compact.

When adding code, keep in mind that it should use the existing facilities in
the source, for performance reasons and for simplicity. Often a review of
existing code doing similar things is helpful.

6) How do I download/update the current source tree?

There are several ways to obtain the source tree. Occasional developers can
just get the most recent source tree snapshot from ftp.postgresql.org. For
regular developers, you can use CVSup, which is available from
ftp.postgresql.org too. CVSup allows you to download the source tree, then
occasionally update your copy of the source tree with any new changes. Using
CVSup, you don't have to download the entire source each time, only the
changed files. CVSup does not allow developers to update the source tree.

Anonymous CVS is available too.  See the doc/FAQ_CVS file for more
information.

To update the source tree, there are two ways. You can generate a patch
against your current source tree, perhaps using the make_diff tools
mentioned above, and send them to the patches list. They will be reviewed,
and applied in a timely manner. If the patch is major, and we are in beta
testing, the developers may wait for the final release before applying your
patches.

For hard-core developers, Marc(scrappy@@postgresql.org) will give you a Unix
shell account on postgresql.org, and you can ftp your files into your
account, patch, and cvs install the changes directly into the source tree.

6) How do I test my changes?

First, use psql to make sure it is working as you expect. Then run
src/test/regress and get the output of src/test/regress/checkresults with
and without your changes, to see that your patch does not change the
regression test in unexpected ways. This practice has saved me many times.
The regression tests test the code in ways I would never do, and has caught
many bugs in my patches. By finding the problems now, you save yourself a
lot of debugging later when things are broken, and you can't figure out when
it happened.
@


1.1
log
@Move FAQ_DEV to docs directory, where it belongs.
@
text
@d116 1
a116 1
regular developers, you can get CVSup, which is available from
d121 3
@
