Skip to content

Commit 1ea069b

Browse files
bmomjianbmomjian
committed
Re-order items, add mention of how to propose working on a TODO item.
1 parent 184e7a7 commit 1ea069b

File tree

2 files changed

+64
-50
lines changed

2 files changed

+64
-50
lines changed

‎doc/FAQ_DEV

Lines changed: 33 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11

22
Developer's Frequently Asked Questions (FAQ) for PostgreSQL
33

4-
Last updated: Fri May 6 13:47:54 EDT 2005
4+
Last updated: Sat May 14 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 is cvs HEAD; if it is a bug fix, this will be the most
117+
version is CVS 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 developers may want to take advantage of anonymous access to
140+
Regular developers might 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 change may
166+
If you've deliberately changed existing behavior, this change might
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, which may 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, which might 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 structure may need code for your new
733-
field. mkid is helpful with this (see 1.9).
739+
files. Find any other places the structure might 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 problems may not be duplicated.
796+
interaction problems might 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

‎doc/src/FAQ/FAQ_DEV.html

Lines changed: 31 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
<H1>Developer's Frequently Asked Questions (FAQ) for
1414
PostgreSQL</H1>
1515

16-
<P>Last updated: Fri May 6 13:47:54 EDT 2005</P>
16+
<P>Last updated: Sat May 14 12:26:01 EDT 2005</P>
1717

1818
<P>Current maintainer: Bruce Momjian (<A href=
1919
"mailto:pgman@candle.pha.pa.us">pgman@candle.pha.pa.us</A>)<BR>
@@ -34,8 +34,8 @@ <H2>General Questions</H2>
3434
<A href="#1.3">1.3</A>) What areas need work?<BR>
3535
<A href="#1.4">1.4</A>) What do I do after choosing an item to
3636
work on?<BR>
37-
<A href="#1.5">1.5</A>) Where can I learn more about the code?<BR>
38-
<A href="#1.6">1.6</A>) I've developed a patch, what next?<BR>
37+
<A href="#1.5">1.5</A>) I've developed a patch, what next?<BR>
38+
<A href="#1.6">1.6</A>) Where can I learn more about the code?<BR>
3939
<A href="#1.7">1.7</A>) How do I download/update the current
4040
source tree?<BR>
4141
<A href="#1.8">1.8</A>) How do I test my changes?<BR>
@@ -139,9 +139,13 @@ <H3><A name="1.4">1.4</A>) What do I do after choosing an item to
139139

140140
<P>Send an email to pgsql-hackers with a proposal for what you want
141141
to do (assuming your contribution is not trivial). Working in
142-
isolation is not advisable: others may be working on the same TODO
143-
item; you may have misunderstood the TODO item; your approach may
144-
benefit from the review of others.</P>
142+
isolation is not advisable because others might be working on the same
143+
TODO item, or you might have misunderstood the TODO item. In the
144+
email, discuss both the internal implementation method you plan to
145+
use, and any user-visible changes (new syntax, etc). For complex
146+
patches, it is important to get community feeback on your proposal
147+
before starting work. Failure to do so might mean your patch is
148+
rejected.</P>
145149

146150
<P>A web site is maintained for patches that are ready to be applied,
147151
<a href="http://momjian.postgresql.org/cgi-bin/pgpatches">
@@ -150,30 +154,33 @@ <H3><A name="1.4">1.4</A>) What do I do after choosing an item to
150154
<a href="http://momjian.postgresql.org/cgi-bin/pgpatches2">
151155
http://momjian.postgresql.org/cgi-bin/pgpatches2</a>.</P>
152156

153-
<H3><A name="1.5">1.5</A>) Where can I learn more about the
154-
code?</H3>
155-
156-
<P>Other than documentation in the source tree itself, you can find
157-
some papers/presentations discussing the code at <A href=
158-
"http://www.postgresql.org/developer">
159-
http://www.postgresql.org/developer</A>.</P>
160-
161-
<H3><A name="1.6">1.6</A>) I've developed a patch, what next?</H3>
157+
<H3><A name="1.5">1.5</A>) I've developed a patch, what next?</H3>
162158

163159
<P>Generate the patch in contextual diff format. If you are
164-
unfamiliar with this, you may find the script
160+
unfamiliar with this, you might find the script
165161
<I>src/tools/makediff/difforig</I> useful.</P>
166162

167163
<P>Ensure that your patch is generated against the most recent
168164
version of the code. If it is a patch adding new functionality, the
169-
most recent version is cvs HEAD; if it is a bug fix, this will be
165+
most recent version is CVS HEAD; if it is a bug fix, this will be
170166
the most recently version of the branch which suffers from the bug
171167
(for more on branches in PostgreSQL, see <A href=
172168
"#1.15">1.15</A>).</P>
173169

174170
<P>Finally, submit the patch to pgsql-patches@postgresql.org. It
175-
will be reviewed by other contributors to the project and may be
176-
either accepted or sent back for further work.</P>
171+
will be reviewed by other contributors to the project and will be
172+
either accepted or sent back for further work. Also, please try to
173+
include documentation changes as part of the patch. If you can't do
174+
that, let us know and we will manually update the documentation when
175+
the patch is applied.</P>
176+
177+
<H3><A name="1.6">1.6</A>) Where can I learn more about the
178+
code?</H3>
179+
180+
<P>Other than documentation in the source tree itself, you can find
181+
some papers/presentations discussing the code at <A href=
182+
"http://www.postgresql.org/developer">
183+
http://www.postgresql.org/developer</A>.</P>
177184

178185
<H3><A name="1.7">1.7</A>) How do I download/update the current
179186
source tree?</H3>
@@ -183,7 +190,7 @@ <H3><A name="1.7">1.7</A>) How do I download/update the current
183190
<A href=
184191
"ftp://ftp.postgresql.org">ftp://ftp.postgresql.org</A>.</P>
185192

186-
<P>Regular developers may want to take advantage of anonymous
193+
<P>Regular developers might want to take advantage of anonymous
187194
access to our source code management system. The source tree is
188195
currently hosted in CVS. For details of how to obtain the source
189196
from CVS see <A href=
@@ -214,7 +221,7 @@ <H3><A name="1.8">1.8</A>) How do I test my changes?</H3>
214221
investigate.</P>
215222

216223
<P>If you've deliberately changed existing behavior, this change
217-
may cause a regression test failure but not any actual regression.
224+
might cause a regression test failure but not any actual regression.
218225
If so, you should also patch the regression test suite.</P>
219226

220227
<P><B>Other run time testing</B></P>
@@ -769,7 +776,7 @@ <H3><A name="2.1">2.1</A>) How do I efficiently access information
769776
delete tuples by passing the tuple's <I>t_self</I> to
770777
<I>heap_destroy().</I> You use <I>t_self</I> for
771778
<I>heap_update()</I> too. Remember, tuples can be either system
772-
cache copies, which may go away after you call
779+
cache copies, which might go away after you call
773780
<I>ReleaseSysCache()</I>, or read directly from disk buffers, which
774781
go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or
775782
<I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may
@@ -904,7 +911,7 @@ <H3><A name="2.4">2.4</A>) I just added a field to a structure.
904911
to create, copy, read, and output those structures (in particular,
905912
the files <I>copyfuncs.c</I> and <I>equalfuncs.c</I>. Make sure you
906913
add support for your new field to these files. Find any other
907-
places the structure may need code for your new field. <I>mkid</I>
914+
places the structure might need code for your new field. <I>mkid</I>
908915
is helpful with this (see <A href="#1.9">1.9</A>).</P>
909916

910917
<H3><A name="2.5">2.5</A>) Why do we use <I>palloc</I>() and
@@ -969,7 +976,7 @@ <H3><A name="2.8">2.8</A>) What debugging features are
969976
symbols, you can use a debugger to see what is happening. Because
970977
the backend was not started from <I>postmaster</I>, it is not
971978
running in an identical environment and locking/backend interaction
972-
problems may not be duplicated.</P>
979+
problems might not be duplicated.</P>
973980

974981
<P>If the <I>postmaster</I> is running, start <I>psql</I> in one
975982
window, then find the <SMALL>PID</SMALL> of the <I>postgres</I>

0 commit comments

Comments
 (0)