On 2021-May-06, Tom Lane wrote:

> Alvaro Herrera <alvhe...@alvh.no-ip.org> writes:

> > 3. add a separate paragraph that says to obtain the source from the
> > other dir if it's the development one.
> > I kinda prefer the last one, because then we could also suggest to use a
> > Git repo instead of a tarball, which I suppose is the best option anyway.
> 
> Yeah.  There is text mentioning the git repo further down, but it's
> hardly prominent.  We should move it up and recommend that as the
> best thing for dev work.

Here are two patches.  v2 is a minimal change; it just adds a
parenthical comment about the snapshot tarball and a mention of "the
text below" which is where the source code repository is mentioned.

v3 rewrites the text more aggressively, so that it opens with
instructions to clone the Git repo, and the released version tarballs
are mentioned further down.  The bad thing about this one is that in the
devel version it still talks about files that don't exist; for example
in branch master it renders as:

        Alternatively, the released versions can be obtained from the download
        section of our website: https://www.postgresql.org/ftp/source/. You
        should get a file named postgresql-15devel.tar.gz or
        postgresql-15devel.tar.bz2. After you have obtained the file, unpack it:

        tar xfa postgresql-15devel.tar.gz
        This will create a directory postgresql-15devel under the current
        directory with the PostgreSQL sources. Change into that directory for
        the rest of the installation procedure.

Now, we *could* make this fully correct by adding
--param pg.version.devel 'true'
(or something like that) to the Makefile, and include paragraphs
conditionally to make it fully correct.  I'm not sure it's worth the
effort.

-- 
Álvaro Herrera           39°49'30"S 73°17'W  —  https://www.EnterpriseDB.com/
>From d000142b596d92463473a28de59a4c9cf78ad771 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvhe...@alvh.no-ip.org>
Date: Tue, 13 Jul 2021 13:06:54 -0400
Subject: [PATCH v2] Improve installation instructions a bit

Reported-by: Daniel Westermann
Discussion: https://postgr.es/m/gv0p278mb04835aaeacf894617574eb6bd2...@gv0p278mb0483.chep278.prod.outlook.com
---
 doc/src/sgml/installation.sgml | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 05b77ec8e6..005d84af3b 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -356,19 +356,17 @@ su - postgres
   <para>
    The <productname>PostgreSQL</productname> &version; sources can be obtained from the
    download section of our
-   website: <ulink url="https://www.postgresql.org/download/";></ulink>.  You
+   website: <ulink url="https://www.postgresql.org/ftp/source/";></ulink>.  You
    should get a file named <filename>postgresql-&version;.tar.gz</filename>
-   or <filename>postgresql-&version;.tar.bz2</filename>. After
-   you have obtained the file, unpack it:
+   or <filename>postgresql-&version;.tar.bz2</filename>.
+   (For the version currently in development, the file is named
+   <filename>postgresql-snapshot.tar.bz2</filename> and resides in
+   <ulink url="https://www.postgresql.org/ftp/snapshot/dev/";></ulink>;
+   but using the version control repository, below, is recommended.)
+   After you have obtained the file, unpack it:
 <screen>
-<userinput>gunzip postgresql-&version;.tar.gz</userinput>
-<userinput>tar xf postgresql-&version;.tar</userinput>
+<userinput>tar xfa postgresql-&version;.tar.gz</userinput>
 </screen>
-   (Use <command>bunzip2</command> instead of <command>gunzip</command> if
-   you have the <filename>.bz2</filename> file.  Also, note that most
-   modern versions of <command>tar</command> can unpack compressed archives
-   directly, so you don't really need the
-   separate <command>gunzip</command> or <command>bunzip2</command> step.)
    This will create a directory
    <filename>postgresql-&version;</filename> under the current directory
    with the <productname>PostgreSQL</productname> sources.
-- 
2.30.2

>From fe16cefa81b248352e06253130746f86acd74c72 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvhe...@alvh.no-ip.org>
Date: Tue, 13 Jul 2021 13:06:54 -0400
Subject: [PATCH v3] Improve installation instructions a bit

Reported-by: Daniel Westermann
Discussion: https://postgr.es/m/gv0p278mb04835aaeacf894617574eb6bd2...@gv0p278mb0483.chep278.prod.outlook.com
---
 doc/src/sgml/installation.sgml | 41 +++++++++++++++++++---------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 05b77ec8e6..5a900da0a3 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -354,32 +354,37 @@ su - postgres
   <title>Getting the Source</title>
 
   <para>
-   The <productname>PostgreSQL</productname> &version; sources can be obtained from the
-   download section of our
-   website: <ulink url="https://www.postgresql.org/download/";></ulink>.  You
-   should get a file named <filename>postgresql-&version;.tar.gz</filename>
-   or <filename>postgresql-&version;.tar.bz2</filename>. After
-   you have obtained the file, unpack it:
+   The version control repository for <productname>PostgreSQL</productname>
+   can be obtained from
+   <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=summary";></ulink>;
+   this is the recommended way to obtain the
+   <productname>PostgreSQL</productname> source code.
+   You can obtain a clone of the repository by running
 <screen>
-<userinput>gunzip postgresql-&version;.tar.gz</userinput>
-<userinput>tar xf postgresql-&version;.tar</userinput>
+<userinput>git clone https://git.postgresql.org/git/postgresql.git</userinput>
+</screen>
+   This will create a directory <filename>postgresql</filename> under the current
+   directory with the <productname>PostgreSQL</productname> sources.
+   Change into that directory for the rest of the installation procedure.
+   See <xref linkend="git"/> for further information.
+  </para>
+
+  <para>
+   Alternatively,
+   the released versions can be obtained from the download section of our
+   website: <ulink url="https://www.postgresql.org/ftp/source/";></ulink>.
+   You should get a file named <filename>postgresql-&version;.tar.gz</filename>
+   or <filename>postgresql-&version;.tar.bz2</filename>.
+   After you have obtained the file, unpack it:
+<screen>
+<userinput>tar xfa postgresql-&version;.tar.gz</userinput>
 </screen>
-   (Use <command>bunzip2</command> instead of <command>gunzip</command> if
-   you have the <filename>.bz2</filename> file.  Also, note that most
-   modern versions of <command>tar</command> can unpack compressed archives
-   directly, so you don't really need the
-   separate <command>gunzip</command> or <command>bunzip2</command> step.)
    This will create a directory
    <filename>postgresql-&version;</filename> under the current directory
    with the <productname>PostgreSQL</productname> sources.
    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="sourcerepo"/>.
-  </para>
  </sect1>
 
  <sect1 id="install-procedure">
-- 
2.30.2

Reply via email to