cvs chapters in our docs
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvs (really, nobody has a 28k8
modem and does cvs over it today. Even your cellphone is orders of
magnitude faster than that).
Other than this patch, I would suggest that we completely remove the
following two chapters:
http://www.postgresql.org/docs/8.4/static/cvs-tree.html -- because
anybody doing anything with branching or tagging today is *not* going
to be using cvs, they will be using git. Let's not lead people down
the wrong path :-)
http://www.postgresql.org/docs/8.4/static/cvsup.html -- does anybody
ever use this? It's a complete PITA to get cvsup working on any
platform I know of. And since we already allow both rsync and git to
get the full repository, there's not much point to it.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Attachments:
cvs_docs.patchapplication/octet-stream; name=cvs_docs.patchDownload
*** a/doc/src/sgml/cvs.sgml
--- b/doc/src/sgml/cvs.sgml
***************
*** 23,45 ****
<date>1999-05-20</date>
</appendixinfo>
! <title>The <productname>CVS</productname> Repository</title>
<para>
The <productname>PostgreSQL</productname> source code is stored and managed using the
! <productname>CVS</productname> version control system.
</para>
<para>
- At least three methods, anonymous CVS, <productname>rsync</productname>,
- and <productname>CVSup</productname>,
- are available to pull the <productname>CVS</productname> code tree from the
- <productname>PostgreSQL</productname> server to your local machine.
Our Wiki, <ulink
! url="http://wiki.postgresql.org/index.php/Working_with_CVS"></ulink>,
! has additional details on working with CVS.
</para>
<sect1 id="anoncvs">
<title>Getting The Source Via Anonymous <productname>CVS</productname></title>
--- 23,120 ----
<date>1999-05-20</date>
</appendixinfo>
! <title>The Source Repository</title>
<para>
The <productname>PostgreSQL</productname> source code is stored and managed using the
! <productname>CVS</productname> version control system. An official mirror using
! <productname>GIT</productname> is also available, for those who wish to use a
! distributed version control system. This mirror is automatically
! updated whenever the main repository changes, so it always contains the latest
! versions of all branches.
! </para>
!
! <para>
! Using <productname>git</> is the most flexible way to work with the source, and it
! allows you to work offline without having constant access to the project servers.
! <productname>CVSup</> and <productname>rsync</> based <productname>cvs</> also
! lets you work offline, but lacks many of the other advantages of
! <productname>git</>.
</para>
<para>
Our Wiki, <ulink
! url="http://wiki.postgresql.org/wiki/Working_with_CVS"></ulink> and
! <ulink url="http://wiki.postgresql.org/wiki/Working_with_Git"></ulink>,
! has additional details on working with CVS and GIT.
</para>
+ <sect1 id="git">
+ <title>Getting The Source Via <productname>GIT</></title>
+
+ <para>
+ With <productname>git</> you will make a copy of the entire code repository
+ to your local machine, so you will have access to all history and branches
+ offline. This is the fastest and most flexible way to develop or test
+ patches.
+ </para>
+
+ <procedure>
+ <title>GIT</title>
+
+ <step>
+ <para>
+ You will need an installed version of <productname>git</>, which you can get
+ from <ulink url="http://git-scm.com"></ulink>. Many systems also have a recent
+ version of <application>git</> installed by default, or available in their
+ package repository system.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ To being using the git repository, make a clone of the official mirror:
+
+ <programlisting>
+ git clone git://git.postgresql.org/git/postgresql.git
+ </programlisting>
+
+ This will copy the full repository to your local machine, so it may take
+ a while to complete, especially if you have a slow internet connection.
+ </para>
+
+ <para>
+ The git mirror can also be reached via the http protocol in case for example
+ a firewall is blocking access to the git protocol. Just replace the URL
+ like:
+
+ <programlisting>
+ git clone http://git.postgresql.org/git/postgresql.git
+ </programlisting>
+
+ The http protocol is less efficient than the git protocol, so it will be
+ slightly slower to use.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Whenever you want to get the latest updates in the system, <command>cd</>
+ into the repository, and run:
+
+ <programlisting>
+ git fetch
+ </programlisting>
+ </para>
+ </step>
+ </procedure>
+ <para>
+ <productname>git</> can do a lot more things than just fetch the source. For
+ more information, consult the man pages for the product, or the website at
+ <ulink url="http://git-scm.com"></>.
+ </para>
+ </sect1>
+
<sect1 id="anoncvs">
<title>Getting The Source Via Anonymous <productname>CVS</productname></title>
***************
*** 92,113 **** cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
This installs the <productname>PostgreSQL</productname> sources into a
subdirectory <filename>pgsql</filename>
of the directory you are currently in.
-
- <note>
- <para>
- If you have a fast link to the Internet, you might not need
- <option>-z3</option>, which instructs
- <productname>CVS</productname> to use <command>gzip</command> compression for transferred data. But
- on a modem-speed link, it's a very substantial win.
- </para>
- </note>
</para>
<para>
This initial checkout is a little slower than simply downloading
! a <filename>tar.gz</filename> file; expect it to take 40 minutes or so if you
! have a 28.8K modem. The advantage of
! <productname>CVS</productname>
doesn't show up until you want to update the file set later on.
</para>
</step>
--- 167,177 ----
This installs the <productname>PostgreSQL</productname> sources into a
subdirectory <filename>pgsql</filename>
of the directory you are currently in.
</para>
<para>
This initial checkout is a little slower than simply downloading
! a <filename>tar.gz</filename> file. The advantage of <productname>CVS</>
doesn't show up until you want to update the file set later on.
</para>
</step>
***************
*** 163,169 **** cvs update
CVS repository. To work around that deficiency, use
<productname>cvsutils</productname>, which is packaged in several
operating systems, and is available in source form at <ulink
! url="http://www.red-bean.com/cvsutils/"></ulink>.
</para>
<para>
--- 227,234 ----
CVS repository. To work around that deficiency, use
<productname>cvsutils</productname>, which is packaged in several
operating systems, and is available in source form at <ulink
! url="http://www.red-bean.com/cvsutils/"></ulink>, or use <productname>git</>
! or another system designed to work offline.
</para>
<para>
***************
*** 301,307 **** cvs commit
An alternative to using anonymous CVS for retrieving the
<productname>PostgreSQL</productname> source tree is
<productname>rsync</productname>, an incremental file transfer tool.
! A major advantage to using <productname>rsync</productname> is that it
can reliably replicate the <emphasis>entire</emphasis> CVS repository
on your local system, allowing fast local access to <command>cvs</>
operations such as <option>log</option> and <option>diff</option>.
--- 366,373 ----
An alternative to using anonymous CVS for retrieving the
<productname>PostgreSQL</productname> source tree is
<productname>rsync</productname>, an incremental file transfer tool.
! A major advantage to using <productname>rsync</productname> instead of
! plain <productname>cvs</> is that it
can reliably replicate the <emphasis>entire</emphasis> CVS repository
on your local system, allowing fast local access to <command>cvs</>
operations such as <option>log</option> and <option>diff</option>.
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvs
I think this whole chapter could be removed and the relevant information
added to the web site or the wiki.
(Btw., it's spelled Git, not GIT.)
On Wed, Nov 25, 2009 at 22:07, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvsI think this whole chapter could be removed and the relevant information
added to the web site or the wiki.(Btw., it's spelled Git, not GIT.)
Completely, or replaced with a reference to pages on the web/wiki?
I don't disagree - if people are fine with that, it sounds good to me.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On ons, 2009-11-25 at 22:15 +0100, Magnus Hagander wrote:
On Wed, Nov 25, 2009 at 22:07, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvsI think this whole chapter could be removed and the relevant information
added to the web site or the wiki.(Btw., it's spelled Git, not GIT.)
Completely, or replaced with a reference to pages on the web/wiki?
I think the appendix in question could be removed completely, if the
content is adequately covered elsewhere.
In the installation instructions chapter, there is a section "Getting
the Source", which could warrant a link or reference to the appropriate
instructions on the web site.
On Thu, Nov 26, 2009 at 2:28 AM, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 22:15 +0100, Magnus Hagander wrote:
On Wed, Nov 25, 2009 at 22:07, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvsI think this whole chapter could be removed and the relevant information
added to the web site or the wiki.(Btw., it's spelled Git, not GIT.)
Completely, or replaced with a reference to pages on the web/wiki?
I think the appendix in question could be removed completely, if the
content is adequately covered elsewhere.In the installation instructions chapter, there is a section "Getting
the Source", which could warrant a link or reference to the appropriate
instructions on the web site.
I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate. Yeah, the
part about 28K modems is pretty silly, but we can fix that without
throwing the baby out with the bathwater...
...Robert
Robert Haas wrote:
On Thu, Nov 26, 2009 at 2:28 AM, Peter Eisentraut <peter_e@gmx.net> wrote:
In the installation instructions chapter, there is a section "Getting
the Source", which could warrant a link or reference to the appropriate
instructions on the web site.I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate.
I agree in general, but information about version control isn't really
part of the product. For example, if we switch from CVS to Git, and
decide to pull the plug on the CVS server (hypotethically; in reality
I'm sure we'd leave the CVS server around for historical purposes), the
information becomes obsolete.
--
Heikki Linnakangas
EnterpriseDB http://www.enterprisedb.com
On Thu, Nov 26, 2009 at 12:29, Robert Haas <robertmhaas@gmail.com> wrote:
On Thu, Nov 26, 2009 at 2:28 AM, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 22:15 +0100, Magnus Hagander wrote:
On Wed, Nov 25, 2009 at 22:07, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvsI think this whole chapter could be removed and the relevant information
added to the web site or the wiki.(Btw., it's spelled Git, not GIT.)
Completely, or replaced with a reference to pages on the web/wiki?
I think the appendix in question could be removed completely, if the
content is adequately covered elsewhere.In the installation instructions chapter, there is a section "Getting
the Source", which could warrant a link or reference to the appropriate
instructions on the web site.I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate. Yeah, the
part about 28K modems is pretty silly, but we can fix that without
throwing the baby out with the bathwater...
Well, my original suggestion had it still there, just not the
documentation that's not really ours to maintain (like how tags and
branches work in cvs). Are you ok with that path? (We already
reference the wiki for "how to work with CVS", so there is nothing new
there)
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Thu, Nov 26, 2009 at 6:44 AM, Magnus Hagander <magnus@hagander.net> wrote:
On Thu, Nov 26, 2009 at 12:29, Robert Haas <robertmhaas@gmail.com> wrote:
On Thu, Nov 26, 2009 at 2:28 AM, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 22:15 +0100, Magnus Hagander wrote:
On Wed, Nov 25, 2009 at 22:07, Peter Eisentraut <peter_e@gmx.net> wrote:
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvsI think this whole chapter could be removed and the relevant information
added to the web site or the wiki.(Btw., it's spelled Git, not GIT.)
Completely, or replaced with a reference to pages on the web/wiki?
I think the appendix in question could be removed completely, if the
content is adequately covered elsewhere.In the installation instructions chapter, there is a section "Getting
the Source", which could warrant a link or reference to the appropriate
instructions on the web site.I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate. Yeah, the
part about 28K modems is pretty silly, but we can fix that without
throwing the baby out with the bathwater...Well, my original suggestion had it still there, just not the
documentation that's not really ours to maintain (like how tags and
branches work in cvs). Are you ok with that path? (We already
reference the wiki for "how to work with CVS", so there is nothing new
there)
Barring protests, I tend to agree that there's little point in keeping
the CVSup documentation around. I don't think it would be a bad thing
to have a little bit of well-written documentation on CVS branches and
tags, especially if it covered things like our particular tagging and
branching conventions. But the current contents of that page don't
appear to be worth much, so I don't think we'd be losing much if we
got rid of it. Of course if someone wanted to rewrite it to be more
useful that might be even better, but I'm not sure anyone wants to put
in the effort.
...Robert
Heikki Linnakangas <heikki.linnakangas@enterprisedb.com> writes:
Robert Haas wrote:
I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate.
I agree in general, but information about version control isn't really
part of the product. For example, if we switch from CVS to Git, and
decide to pull the plug on the CVS server (hypotethically; in reality
I'm sure we'd leave the CVS server around for historical purposes), the
information becomes obsolete.
If our docs are supposed to cover only information that's not subject
to change, they'll become quite short. I agree with Robert that moving
the info from the SGML docs to the wiki isn't an improvement.
regards, tom lane
On Thu, Nov 26, 2009 at 16:38, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Heikki Linnakangas <heikki.linnakangas@enterprisedb.com> writes:
Robert Haas wrote:
I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate.I agree in general, but information about version control isn't really
part of the product. For example, if we switch from CVS to Git, and
decide to pull the plug on the CVS server (hypotethically; in reality
I'm sure we'd leave the CVS server around for historical purposes), the
information becomes obsolete.If our docs are supposed to cover only information that's not subject
to change, they'll become quite short. I agree with Robert that moving
the info from the SGML docs to the wiki isn't an improvement.
I assume you are fine with the addition of some info about git, but
what about the removal of those two chapters suggested?
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Magnus Hagander <magnus@hagander.net> writes:
I assume you are fine with the addition of some info about git, but
what about the removal of those two chapters suggested?
I agree that we needn't try to cover material that's in the CVS manual.
As somebody mentioned upthread, a sentence or two about our branching
and tagging conventions would be a lot more useful.
regards, tom lane
peter_e@gmx.net (Peter Eisentraut) writes:
On ons, 2009-11-25 at 16:27 +0100, Magnus Hagander wrote:
Attached is a patch which adds a chapter to git in our documentation,
around where we have several chapters about cvs today. It also removes
a few very out of date comments about cvsI think this whole chapter could be removed and the relevant information
added to the web site or the wiki.(Btw., it's spelled Git, not GIT.)
I think I'd rather see the documentation repaired in the CVS repository
where it happens to reside today.
Wikis have a habit of getting out of date in ways that make them even
more difficult to rectify, because the data is frequently structured in
a way that doesn't make it particularly easy to pull it out and
transform it into other forms.
Now, if someone knows a way of creating a Git repository[1]Or Darcs, Mercurial, SVN, or whatever... -- wm(X,Y):-write(X),write('@'),write(Y). wm('cbbrowne','linuxfinances.info'). http://www3.sympatico.ca/cbbrowne/ Dijkstra probably hates me (Linus Torvalds, in kernel/sched.c) that tracks,
change-for-change, everything going on in a MediaWiki repository in a
textual form that would allow one to monitor everything going on, and
possibly even inject changes, that *would* be something.
(To *my* mind, the ultimate wiki platform that I have seen lately is
ikiwiki <http://ikiwiki.info/>, which manages the wiki in an SCM,
"compiling" the pages into HTML whenever things are changed. Should
cope with heavy query load rather well! But I digress...)
Footnotes:
[1]: Or Darcs, Mercurial, SVN, or whatever... -- wm(X,Y):-write(X),write('@'),write(Y). wm('cbbrowne','linuxfinances.info'). http://www3.sympatico.ca/cbbrowne/ Dijkstra probably hates me (Linus Torvalds, in kernel/sched.c)
--
wm(X,Y):-write(X),write('@'),write(Y). wm('cbbrowne','linuxfinances.info').
http://www3.sympatico.ca/cbbrowne/
Dijkstra probably hates me
(Linus Torvalds, in kernel/sched.c)
Robert Haas wrote:
I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate. Yeah, the
part about 28K modems is pretty silly, but we can fix that without
throwing the baby out with the bathwater...
Wow, we mention 28k modems --- we are legacy software: ;-)
This initial checkout is a little slower than simply downloading
a <filename>tar.gz</filename> file; expect it to take 40 minutes
or so if you have a 28.8K modem.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <bruce@momjian.us> writes:
Robert Haas wrote:
I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate. Yeah, the
part about 28K modems is pretty silly, but we can fix that without
throwing the baby out with the bathwater...
Wow, we mention 28k modems --- we are legacy software: ;-)
The depressing thing is we can't even blame that on Berkeley ...
if memory serves, I wrote it :-(
regards, tom lane
Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
Robert Haas wrote:
I have to say I'm not really impressed by the idea of removing things
from our documentation and replacing them with pages on the wiki. The
documentation is better-written and easier to navigate. Yeah, the
part about 28K modems is pretty silly, but we can fix that without
throwing the baby out with the bathwater...Wow, we mention 28k modems --- we are legacy software: ;-)
The depressing thing is we can't even blame that on Berkeley ...
if memory serves, I wrote it :-(
There is no mention of paper tape or punch cards in our docs. :-)
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
2009/11/29 Bruce Momjian <bruce@momjian.us>:
Wow, we mention 28k modems --- we are legacy software: ;-)
This initial checkout is a little slower than simply downloading
a <filename>tar.gz</filename> file; expect it to take 40 minutes
or so if you have a 28.8K modem.
Yes, and what about all the people using carrier pidgeon to download
Postgres? I think our documentation is neglecting this substantial
and vital portion of our user community.
Cheers,
BJ
Brendan Jurd wrote:
2009/11/29 Bruce Momjian <bruce@momjian.us>:
Wow, we mention 28k modems --- we are legacy software: ;-)
This initial checkout is a little slower than simply downloading
a <filename>tar.gz</filename> file; expect it to take 40 minutes
or so if you have a 28.8K modem.Yes, and what about all the people using carrier pidgeon to download
Postgres? I think our documentation is neglecting this substantial
and vital portion of our user community.
Never underestimate the bandwidth of a carrier pigeon with a flash
card tied to his leg. [1]http://www.dslreports.com/shownews/Carrier-Pigeon-Officially-Beats-DSL-104393
"11-month-old bird armed with a 4GB memory stick... the carrier pigeon
delivered 4GB of data 60 miles in a little over an hour"
[1]: http://www.dslreports.com/shownews/Carrier-Pigeon-Officially-Beats-DSL-104393
Chris Browne wrote:
Wikis have a habit of getting out of date in ways that make them even
more difficult to rectify, because the data is frequently structured in
a way that doesn't make it particularly easy to pull it out and
transform it into other forms.
The standard way to backup a Mediawiki install is to export to XML:
http://meta.wikimedia.org/wiki/Help:Export
At which point you can transform it as easily as any other structured
document and then re-import.
Given that the pages on the PostgreSQL wiki about CVS and Git have been
the most up to date resources on those topics available since shortly
after their respective creation dates, I'm not sure what one could
criticize about them as an information source in this area.
--
Greg Smith 2ndQuadrant Baltimore, MD
PostgreSQL Training, Services and Support
greg@2ndQuadrant.com www.2ndQuadrant.com
2009/11/26 Tom Lane <tgl@sss.pgh.pa.us>:
Magnus Hagander <magnus@hagander.net> writes:
I assume you are fine with the addition of some info about git, but
what about the removal of those two chapters suggested?I agree that we needn't try to cover material that's in the CVS manual.
As somebody mentioned upthread, a sentence or two about our branching
and tagging conventions would be a lot more useful.
Here's an updated patch that does what I believe the consensus of this
thread was. Unless objected, I will commit this later tonight. Patch
now does:
* As before, update cvs documentation and add git documentation
* Remove cvsup documentation
* Remove cvs internal documentation
* Add a link to appendix H (the source code repository) from the
general getting the source chapter.
It does not add any proper documentation of exactly how we deal with
branches and tags at a useful level - this will come later.
I would also like to propose that we actually backpatch this. At least
the addition of the git documentation and the update of the CVS
documentation. So we get this info out there. We don't normally
backpatch things like this though, so comments on that?
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Attachments:
cvs_docs.patchapplication/octet-stream; name=cvs_docs.patchDownload
*** a/doc/src/sgml/cvs.sgml
--- b/doc/src/sgml/cvs.sgml
***************
*** 23,45 ****
<date>1999-05-20</date>
</appendixinfo>
! <title>The <productname>CVS</productname> Repository</title>
<para>
The <productname>PostgreSQL</productname> source code is stored and managed using the
! <productname>CVS</productname> version control system.
</para>
<para>
- At least three methods, anonymous CVS, <productname>rsync</productname>,
- and <productname>CVSup</productname>,
- are available to pull the <productname>CVS</productname> code tree from the
- <productname>PostgreSQL</productname> server to your local machine.
Our Wiki, <ulink
! url="http://wiki.postgresql.org/index.php/Working_with_CVS"></ulink>,
! has additional details on working with CVS.
</para>
<sect1 id="anoncvs">
<title>Getting The Source Via Anonymous <productname>CVS</productname></title>
--- 23,120 ----
<date>1999-05-20</date>
</appendixinfo>
! <title>The Source Code Repository</title>
<para>
The <productname>PostgreSQL</productname> source code is stored and managed using the
! <productname>CVS</productname> version control system. An official mirror using
! <productname>Git</productname> is also available, for those who wish to use a
! distributed version control system. This mirror is automatically
! updated whenever the main repository changes, so it always contains the latest
! versions of all branches.
! </para>
!
! <para>
! Using <productname>git</> is the most flexible way to work with the source, and it
! allows you to work offline without having constant access to the project servers.
! <productname>CVSup</> and <productname>rsync</> based <productname>cvs</> also
! lets you work offline, but lacks many of the other advantages of
! <productname>git</>.
</para>
<para>
Our Wiki, <ulink
! url="http://wiki.postgresql.org/wiki/Working_with_CVS"></ulink> and
! <ulink url="http://wiki.postgresql.org/wiki/Working_with_Git"></ulink>,
! has additional details on working with CVS and Git.
</para>
+ <sect1 id="git">
+ <title>Getting The Source Via <productname>Git</></title>
+
+ <para>
+ With <productname>git</> you will make a copy of the entire code repository
+ to your local machine, so you will have access to all history and branches
+ offline. This is the fastest and most flexible way to develop or test
+ patches.
+ </para>
+
+ <procedure>
+ <title>Git</title>
+
+ <step>
+ <para>
+ You will need an installed version of <productname>git</>, which you can get
+ from <ulink url="http://git-scm.com"></ulink>. Many systems also have a recent
+ version of <application>git</> installed by default, or available in their
+ package repository system.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ To being using the git repository, make a clone of the official mirror:
+
+ <programlisting>
+ git clone git://git.postgresql.org/git/postgresql.git
+ </programlisting>
+
+ This will copy the full repository to your local machine, so it may take
+ a while to complete, especially if you have a slow internet connection.
+ </para>
+
+ <para>
+ The git mirror can also be reached via the http protocol in case for example
+ a firewall is blocking access to the git protocol. Just replace the URL
+ like:
+
+ <programlisting>
+ git clone http://git.postgresql.org/git/postgresql.git
+ </programlisting>
+
+ The http protocol is less efficient than the git protocol, so it will be
+ slightly slower to use.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Whenever you want to get the latest updates in the system, <command>cd</>
+ into the repository, and run:
+
+ <programlisting>
+ git fetch
+ </programlisting>
+ </para>
+ </step>
+ </procedure>
+ <para>
+ <productname>git</> can do a lot more things than just fetch the source. For
+ more information, consult the man pages for the product, or the website at
+ <ulink url="http://git-scm.com"></>.
+ </para>
+ </sect1>
+
<sect1 id="anoncvs">
<title>Getting The Source Via Anonymous <productname>CVS</productname></title>
***************
*** 92,113 **** cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
This installs the <productname>PostgreSQL</productname> sources into a
subdirectory <filename>pgsql</filename>
of the directory you are currently in.
-
- <note>
- <para>
- If you have a fast link to the Internet, you might not need
- <option>-z3</option>, which instructs
- <productname>CVS</productname> to use <command>gzip</command> compression for transferred data. But
- on a modem-speed link, it's a very substantial win.
- </para>
- </note>
</para>
<para>
This initial checkout is a little slower than simply downloading
! a <filename>tar.gz</filename> file; expect it to take 40 minutes or so if you
! have a 28.8K modem. The advantage of
! <productname>CVS</productname>
doesn't show up until you want to update the file set later on.
</para>
</step>
--- 167,177 ----
This installs the <productname>PostgreSQL</productname> sources into a
subdirectory <filename>pgsql</filename>
of the directory you are currently in.
</para>
<para>
This initial checkout is a little slower than simply downloading
! a <filename>tar.gz</filename> file. The advantage of <productname>CVS</>
doesn't show up until you want to update the file set later on.
</para>
</step>
***************
*** 163,169 **** cvs update
CVS repository. To work around that deficiency, use
<productname>cvsutils</productname>, which is packaged in several
operating systems, and is available in source form at <ulink
! url="http://www.red-bean.com/cvsutils/"></ulink>.
</para>
<para>
--- 227,234 ----
CVS repository. To work around that deficiency, use
<productname>cvsutils</productname>, which is packaged in several
operating systems, and is available in source form at <ulink
! url="http://www.red-bean.com/cvsutils/"></ulink>, or use <productname>git</>
! or another system designed to work offline.
</para>
<para>
***************
*** 176,299 **** cvs update
</para>
</sect1>
- <sect1 id="cvs-tree">
- <title><productname>CVS</productname> Tree Organization</title>
-
- <para>
- <note>
- <title>Author</title>
- <para>
- Written by Marc G. Fournier (<email>scrappy@hub.org</email>) on 1998-11-05
- </para>
- </note>
- </para>
-
- <para>
- The command <command>cvs checkout</command> has a flag, <option>-r</option>,
- that lets you check out a
- certain revision of a module. This flag makes it easy to, for example,
- retrieve the
- sources that make up release 6_4 of the module `tc' at any time in the
- future:
-
- <programlisting>
- cvs checkout -r REL6_4 tc
- </programlisting>
-
- This is useful, for instance, if someone claims that there is a bug in
- that release, but you cannot find the bug in the current working copy.
-
- <tip>
- <para>
- You can also check out a module as it was at any given date using the
- <option>-D</option> option.
- </para>
- </tip>
- </para>
-
- <para>
- When you tag more than one file with the same tag you can think
- about the tag as <quote>a curve drawn through a matrix of file name vs.
- revision number</quote>. Say we have 5 files with the following revisions:
-
- <programlisting>
- file1 file2 file3 file4 file5
-
- 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
- 1.2*- 1.2 1.2 -1.2*-
- 1.3 \- 1.3*- 1.3 / 1.3
- 1.4 \ 1.4 / 1.4
- \-1.5*- 1.5
- 1.6
- </programlisting>
-
- then the tag <literal>TAG</literal> will reference
- file1-1.2, file2-1.3, etc.
-
- <note>
- <para>
- For creating a release branch, other than a
- <literal>-b</> option added to the command, it's the same thing.</para>
- </note>
- </para>
-
- <para>
- So, to create the 6.4 release
- I did the following:
-
- <programlisting>
- cd pgsql
- cvs tag -b REL6_4
- </programlisting>
-
- which will create the tag and the branch for the RELEASE tree.
- </para>
-
- <para>
- For those with <productname>CVS</productname> access, it's simple to
- create directories for different versions.
- First, create two subdirectories, RELEASE and CURRENT, so that you don't
- mix up the two. Then do:
-
- <programlisting>
- cd RELEASE
- cvs checkout -P -r REL6_4 pgsql
- cd ../CURRENT
- cvs checkout -P pgsql
- </programlisting>
-
- which results in two directory trees, <filename>RELEASE/pgsql</filename> and
- <filename>CURRENT/pgsql</filename>. From that point on,
- <productname>CVS</productname>
- will keep track of which repository branch is in which directory tree, and will
- allow independent updates of either tree.
- </para>
-
- <para>
- If you are <emphasis>only</emphasis> working on the <literal>CURRENT</literal>
- source tree, you just do
- everything as before we started tagging release branches.
- </para>
-
- <para>
- After you've done the initial checkout on a branch:
-
- <programlisting>
- cvs checkout -r REL6_4
- </programlisting>
-
- anything you do within that directory structure is restricted to that
- branch. If you apply a patch to that directory structure and do a:
-
- <programlisting>
- cvs commit
- </programlisting>
-
- while inside of it, the patch is applied to the branch and
- <emphasis>only</emphasis> the branch.
- </para>
- </sect1>
-
<sect1 id="rsync">
<title>Getting The Source Via <productname>rsync</productname></title>
--- 241,246 ----
***************
*** 301,307 **** cvs commit
An alternative to using anonymous CVS for retrieving the
<productname>PostgreSQL</productname> source tree is
<productname>rsync</productname>, an incremental file transfer tool.
! A major advantage to using <productname>rsync</productname> is that it
can reliably replicate the <emphasis>entire</emphasis> CVS repository
on your local system, allowing fast local access to <command>cvs</>
operations such as <option>log</option> and <option>diff</option>.
--- 248,255 ----
An alternative to using anonymous CVS for retrieving the
<productname>PostgreSQL</productname> source tree is
<productname>rsync</productname>, an incremental file transfer tool.
! A major advantage to using <productname>rsync</productname> instead of
! plain <productname>cvs</> is that it
can reliably replicate the <emphasis>entire</emphasis> CVS repository
on your local system, allowing fast local access to <command>cvs</>
operations such as <option>log</option> and <option>diff</option>.
***************
*** 321,507 **** rsync -avzH --delete anoncvs.postgresql.org::pgsql-cvs cvsroot/
pgbuildfarm instructions</ulink>.
</para>
</sect1>
-
- <sect1 id="cvsup">
- <title>Getting The Source Via <productname>CVSup</productname></title>
-
- <para>
- Another alternative to using anonymous CVS for retrieving
- the <productname>PostgreSQL</productname> source tree
- is <productname>CVSup</productname>.
- <productname>CVSup</productname> was developed by
- John Polstra (<email>jdp@polstra.com</email>) to
- distribute CVS repositories and other file trees for the
- <ulink url="http://www.freebsd.org">FreeBSD project</ulink>.
- </para>
-
- <sect2>
- <title>Preparing A <productname>CVSup</productname> Client System</title>
-
- <para>
- Two directory areas are required for <productname>CVSup</productname>
- to do its job: a local <productname>CVS</productname> repository
- (or simply a directory area if you are fetching a snapshot rather
- than a repository; see below)
- and a local <productname>CVSup</productname> bookkeeping
- area. These can coexist in the same directory tree.
- </para>
-
- <para>
- Decide where you want to keep your local copy of the
- <productname>CVS</productname> repository. On one of our systems we
- recently set up a repository in <filename>/home/cvs/</filename>,
- but had formerly kept it under a
- <productname>PostgreSQL</productname> development tree in
- <filename>/opt/postgres/cvs/</filename>. If you intend to keep your
- repository in <filename>/home/cvs/</filename>, then put:
-
- <programlisting>
- setenv CVSROOT /home/cvs
- </programlisting>
-
- in your <filename>.cshrc</filename> file, or a similar line in
- your <filename>.bashrc</filename> or
- <filename>.profile</filename> file, depending on your shell.
- </para>
-
- <para>
- The <application>cvs</application> repository area must be initialized.
- Once <envar>CVSROOT</envar> is set, then this can be done with a
- single command:
-
- <programlisting>
- cvs init
- </programlisting>
-
- after which you should see at least a directory named
- <filename>CVSROOT</filename> when listing the
- <envar>CVSROOT</envar> directory:
-
- <programlisting>
- $ ls $CVSROOT
- CVSROOT/
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Running a <productname>CVSup</productname> Client</title>
-
- <para>
- Verify that
- <application>cvsup</application> is in your path; on most systems
- you can do this by typing:
-
- <programlisting>
- which cvsup
- </programlisting>
-
- Then, simply run
- <application>cvsup</application> using:
-
- <programlisting>
- cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable>
- </programlisting>
-
- where <option>-L 2</option> enables some status messages so you
- can monitor the progress of the update,
- and <replaceable class="parameter">postgres.cvsup</replaceable> is
- the path and name you have given to your
- <productname>CVSup</productname> configuration file.
- </para>
-
- <para>
- Here is a <productname>CVSup</productname> configuration file
- modified for a specific installation, and which maintains a full
- local <productname>CVS</productname> repository:
-
- <programlisting>
- # This file represents the standard CVSup distribution file
- # for the <productname>PostgreSQL</> ORDBMS project
- # Modified by lockhart@fourpalms.org 1997-08-28
- # - Point to my local snapshot source tree
- # - Pull the full CVS repository, not just the latest snapshot
- #
- # Defaults that apply to all the collections
- *default host=cvsup.postgresql.org
- *default compress
- *default release=cvs
- *default delete use-rel-suffix
- # enable the following line to get the latest snapshot
- #*default tag=.
- # enable the following line to get whatever was specified above or by default
- # at the date specified below
- #*default date=97.08.29.00.00.00
-
- # base directory where CVSup will store its 'bookmarks' file(s)
- # will create subdirectory sup/
- #*default base=/opt/postgres # /usr/local/pgsql
- *default base=/home/cvs
-
- # prefix directory where CVSup will store the actual distribution(s)
- *default prefix=/home/cvs
-
- # complete distribution, including all below
- pgsql
-
- # individual distributions vs 'the whole thing'
- # pgsql-doc
- # pgsql-perl5
- # pgsql-src
- </programlisting>
- </para>
-
- <para>
- If you specify <option>repository</> instead of <option>pgsql</>
- in the above setup, you will get a complete copy of the entire
- repository at cvsup.postgresql.org, including its
- <filename>CVSROOT</filename> directory. If you do that, you will
- probably want to exclude those files in that directory that you
- want to modify locally, using a refuse file. For example, for the
- above setup you might put this in
- <filename>/home/cvs/sup/repository/refuse</>:
- <programlisting>
- CVSROOT/config*
- CVSROOT/commitinfo*
- CVSROOT/loginfo*
- </programlisting>
- See the <productname>CVSup</> manual pages for how to use refuse files.
- </para>
-
- <para>
- The following is a suggested <productname>CVSup</productname> configuration file from
- the <productname>PostgreSQL</>
- <ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">
- ftp site</ulink>
- which will fetch the current snapshot only:
-
- <programlisting>
- # This file represents the standard CVSup distribution file
- # for the <productname>PostgreSQL</> ORDBMS project
- #
- # Defaults that apply to all the collections
- *default host=cvsup.postgresql.org
- *default compress
- *default release=cvs
- *default delete use-rel-suffix
- *default tag=.
-
- # base directory where CVSup will store its 'bookmarks' file(s)
- *default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>
-
- # prefix directory where CVSup will store the actual distribution(s)
- *default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>
-
- # complete distribution, including all below
- pgsql
-
- # individual distributions vs 'the whole thing'
- # pgsql-doc
- # pgsql-perl5
- # pgsql-src
- </programlisting>
- </para>
- </sect2>
- </sect1>
</appendix>
--- 269,272 ----
*** a/doc/src/sgml/installation.sgml
--- b/doc/src/sgml/installation.sgml
***************
*** 354,359 **** su - postgres
--- 354,364 ----
Change into that directory for the rest
of the installation procedure.
</para>
+
+ <para>
+ You can also get the source directly from the version control repository, see
+ <xref linkend="cvs">.
+ </para>
</sect1>
]]>
On Mon, Dec 07, 2009 at 04:08:28PM +0100, Magnus Hagander wrote:
2009/11/26 Tom Lane <tgl@sss.pgh.pa.us>:
Magnus Hagander <magnus@hagander.net> writes:
I assume you are fine with the addition of some info about git, but
what about the removal of those two chapters suggested?I agree that we needn't try to cover material that's in the CVS manual.
As somebody mentioned upthread, a sentence or two about our branching
and tagging conventions would be a lot more useful.Here's an updated patch that does what I believe the consensus of this
thread was. Unless objected, I will commit this later tonight. Patch
now does:* As before, update cvs documentation and add git documentation
* Remove cvsup documentation
* Remove cvs internal documentation
* Add a link to appendix H (the source code repository) from the
general getting the source chapter.It does not add any proper documentation of exactly how we deal with
branches and tags at a useful level - this will come later.I would also like to propose that we actually backpatch this. At least
the addition of the git documentation and the update of the CVS
documentation. So we get this info out there. We don't normally
backpatch things like this though, so comments on that?
+1 for back-patching.
Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics
Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate
Magnus Hagander <magnus@hagander.net> writes:
I would also like to propose that we actually backpatch this. At least
the addition of the git documentation and the update of the CVS
documentation. So we get this info out there. We don't normally
backpatch things like this though, so comments on that?
The sort of people who would actually have a use for the information
are unlikely to be looking at back branches, so I don't particularly
see the point. But if you wanna do the work ...
regards, tom lane
2009/12/7 Tom Lane <tgl@sss.pgh.pa.us>:
Magnus Hagander <magnus@hagander.net> writes:
I would also like to propose that we actually backpatch this. At least
the addition of the git documentation and the update of the CVS
documentation. So we get this info out there. We don't normally
backpatch things like this though, so comments on that?The sort of people who would actually have a use for the information
are unlikely to be looking at back branches, so I don't particularly
see the point. But if you wanna do the work ...
I'd do 8.4, becuase that's what shows up under /current/ on the website.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Magnus Hagander escribi�:
2009/12/7 Tom Lane <tgl@sss.pgh.pa.us>:
Magnus Hagander <magnus@hagander.net> writes:
I would also like to propose that we actually backpatch this. At least
the addition of the git documentation and the update of the CVS
documentation. So we get this info out there. We don't normally
backpatch things like this though, so comments on that?The sort of people who would actually have a use for the information
are unlikely to be looking at back branches, so I don't particularly
see the point. �But if you wanna do the work ...I'd do 8.4, becuase that's what shows up under /current/ on the website.
8.4 makes sense to me.
--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support