11
22 Developer's Frequently Asked Questions (FAQ) for PostgreSQL
33
4- Last updated:Fri May6 13:47:54 EDT 2005
4+ Last updated:Sat May14 12:26:01 EDT 2005
55
66 Current maintainer: Bruce Momjian (pgman@candle.pha.pa.us)
77
@@ -15,8 +15,8 @@ General Questions
1515 1.2) What development environment is required to develop code?
1616 1.3) What areas need work?
1717 1.4) What do I do after choosing an item to work on?
18- 1.5)Where can I learn more about the code ?
19- 1.6)I've developed a patch, what next ?
18+ 1.5)I've developed a patch, what next ?
19+ 1.6)Where can I learn more about the code ?
2020 1.7) How do I download/update the current source tree?
2121 1.8) How do I test my changes?
2222 1.9) What tools are available for developers?
@@ -94,43 +94,50 @@ General Questions
9494
9595 Send an email to pgsql-hackers with a proposal for what you want to do
9696 (assuming your contribution is not trivial). Working in isolation is
97- not advisable: others may be working on the same TODO item; you may
98- have misunderstood the TODO item; your approach may benefit from the
99- review of others.
97+ not advisable because others might be working on the same TODO item,
98+ or you might have misunderstood the TODO item. In the email, discuss
99+ both the internal implementation method you plan to use, and any
100+ user-visible changes (new syntax, etc). For complex patches, it is
101+ important to get community feeback on your proposal before starting
102+ work. Failure to do so might mean your patch is rejected.
100103
101104 A web site is maintained for patches that are ready to be applied,
102105 http://momjian.postgresql.org/cgi-bin/pgpatches, and those that are
103106 being kept for the next release,
104107 http://momjian.postgresql.org/cgi-bin/pgpatches2.
105108
106- 1.5) Where can I learn more about the code?
107-
108- Other than documentation in the source tree itself, you can find some
109- papers/presentations discussing the code at
110- http://www.postgresql.org/developer.
111-
112- 1.6) I've developed a patch, what next?
109+ 1.5) I've developed a patch, what next?
113110
114111 Generate the patch in contextual diff format. If you are unfamiliar
115- with this, you may find the script src/tools/makediff/difforig useful.
112+ with this, you might find the script src/tools/makediff/difforig
113+ useful.
116114
117115 Ensure that your patch is generated against the most recent version of
118116 the code. If it is a patch adding new functionality, the most recent
119- version iscvs HEAD; if it is a bug fix, this will be the most
117+ version isCVS HEAD; if it is a bug fix, this will be the most
120118 recently version of the branch which suffers from the bug (for more on
121119 branches in PostgreSQL, see 1.15).
122120
123121 Finally, submit the patch to pgsql-patches@postgresql.org. It will be
124- reviewed by other contributors to the project and may be either
125- accepted or sent back for further work.
122+ reviewed by other contributors to the project and will be either
123+ accepted or sent back for further work. Also, please try to include
124+ documentation changes as part of the patch. If you can't do that, let
125+ us know and we will manually update the documentation when the patch
126+ is applied.
127+
128+ 1.6) Where can I learn more about the code?
129+
130+ Other than documentation in the source tree itself, you can find some
131+ papers/presentations discussing the code at
132+ http://www.postgresql.org/developer.
126133
127134 1.7) How do I download/update the current source tree?
128135
129136 There are several ways to obtain the source tree. Occasional
130137 developers can just get the most recent source tree snapshot from
131138 ftp://ftp.postgresql.org.
132139
133- Regular developersmay want to take advantage of anonymous access to
140+ Regular developersmight want to take advantage of anonymous access to
134141 our source code management system. The source tree is currently hosted
135142 in CVS. For details of how to obtain the source from CVS see
136143 http://developer.postgresql.org/docs/postgres/cvs.html.
@@ -156,7 +163,7 @@ General Questions
156163 test suite. To do this, issue "make check" in the root directory of
157164 the source tree. If any tests failure, investigate.
158165
159- If you've deliberately changed existing behavior, this changemay
166+ If you've deliberately changed existing behavior, this changemight
160167 cause a regression test failure but not any actual regression. If so,
161168 you should also patch the regression test suite.
162169
@@ -625,10 +632,10 @@ Technical Questions
625632 values you want changed. It returns a palloc'ed tuple, which you pass
626633 to heap_replace(). You can delete tuples by passing the tuple's t_self
627634 to heap_destroy(). You use t_self for heap_update() too. Remember,
628- tuples can be either system cache copies, whichmay go away after you
629- call ReleaseSysCache(), or read directly from disk buffers, which go
630- away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
631- heap_fetch() case. Or it may be a palloc'ed tuple, that you must
635+ tuples can be either system cache copies, whichmight go away after
636+ you call ReleaseSysCache(), or read directly from disk buffers, which
637+ go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in
638+ the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
632639 pfree() when finished.
633640
634641 2.2) Why are table, column, type, function, view names sometimes referenced
@@ -729,8 +736,8 @@ typedef struct nameData
729736 routines in src/backend/nodes used to create, copy, read, and output
730737 those structures (in particular, the files copyfuncs.c and
731738 equalfuncs.c. Make sure you add support for your new field to these
732- files. Find any other places the structuremay need code for your new
733- field. mkid is helpful with this (see 1.9).
739+ files. Find any other places the structuremight need code for your
740+ new field. mkid is helpful with this (see 1.9).
734741
735742 2.5) Why do we use palloc() and pfree() to allocate memory?
736743
@@ -786,7 +793,7 @@ typedef struct nameData
786793 with debugging symbols, you can use a debugger to see what is
787794 happening. Because the backend was not started from postmaster, it is
788795 not running in an identical environment and locking/backend
789- interaction problemsmay not be duplicated.
796+ interaction problemsmight not be duplicated.
790797
791798 If the postmaster is running, start psql in one window, then find the
792799 PID of the postgres process used by psql using SELECT