Link t the souce code

Hello

On 2021-May-04, Daniel Westermann (DWE) wrote:

reading this: https://www.postgresql.org/docs/13/install-getsource.html
...
I wonder if the link should not directly point to the relevant release, e.g.:
https://www.postgresql.org/ftp/source/v13.2/

To me that seems to be more convenient than figuring that out on
https://www.postgresql.org/download/. The initial page is about
getting the source code, so links to packages/binaries are not
required if someone is looking for the source.

I agree -- if the user wanted packages, they would not be reading that
page of the docs. I'd just have it point to the same page that the
download page points to for source downloads, not a version-specific
one, as in the attached patch.

How does it look?

--
�lvaro Herrera 39�49'30"S 73�17'W

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

I agree -- if the user wanted packages, they would not be reading that
page of the docs. I'd just have it point to the same page that the
download page points to for source downloads, not a version-specific
one, as in the attached patch.

+1. I think people reading this may have their own ideas about
which version they want. Also, getting the link to be sane in
the devel docs might be problematic.

regards, tom lane

On 5/6/21 6:05 PM, Tom Lane wrote:

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

I agree -- if the user wanted packages, they would not be reading that
page of the docs. I'd just have it point to the same page that the
download page points to for source downloads, not a version-specific
one, as in the attached patch.

+1. I think people reading this may have their own ideas about
which version they want. Also, getting the link to be sane in
the devel docs might be problematic.

+1 on all of the above.

Jonathan

On 2021-May-06, Jonathan S. Katz wrote:

On 5/6/21 6:05 PM, Tom Lane wrote:

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

I agree -- if the user wanted packages, they would not be reading that
page of the docs. I'd just have it point to the same page that the
download page points to for source downloads, not a version-specific
one, as in the attached patch.

+1. I think people reading this may have their own ideas about
which version they want. Also, getting the link to be sane in
the devel docs might be problematic.

+1 on all of the above.

This text seems to work fine for released versions, but not very well
for development, because it says this:

The PostgreSQL 14devel sources can be obtained from the download section
of our website: https://www.postgresql.org/ftp/source/. You should get a
file named postgresql-14devel.tar.gz or postgresql-14devel.tar.bz2.

and no such thing as postgresql-14devel.tar.gz can be found anywhere as
far as I can see. What we do have is postgresql-snapshot.tar.gz, but
that's not located in /ftp/source/ but /ftp/snapshot/dev/.

I think if we wanted to be tense about these instructions being correct
for the devel version, we need more work. Options I can see:

1. add a directory for the current devel version in the FTP area.

2. use conditional XML markup that points to the snapshot dir when doing
the devel build

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.

--
�lvaro Herrera 39�49'30"S 73�17'W

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

This text seems to work fine for released versions, but not very well
for development, because it says this:

True.

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.

regards, tom lane

On 2021-May-06, Tom Lane wrote:

Alvaro Herrera <alvherre@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/

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

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.

ISTM that specifying an exact version number here is rather pointless
anyway. Could we drop the reference to an exact file name, and write
something like

Alternatively, source code for released versions can be obtained
from the download section of our website:
https://www.postgresql.org/ftp/source/.
Download the postgresql-<replaceable>version</replaceable>.tar.gz or
postgresql-<replaceable>version</replaceable>.tar.bz2 file for the
version you are interested in, then unpack it:
tar xfa postgresql-<replaceable>version</replaceable>.tar.gz
This will create a directory
postgresql-<replaceable>version</replaceable> under the current ...

Admittedly, someone who doesn't grok that
<replaceable>version</replaceable> is a variable might be confused
initially, but I think they'd soon figure it out after seeing the
file names on the server.

regards, tom lane

On 21.07.21 01:45, Alvaro Herrera wrote:

<screen>
-<userinput>gunzip postgresql-&version;.tar.gz</userinput>
-<userinput>tar xf postgresql-&version;.tar</userinput>
+<userinput>tar xfa postgresql-&version;.tar.gz</userinput>
</screen>

The "a" option only applies when creating a tar archive ("c" command).
So adding it here does nothing.

On 2021-Jul-21, Peter Eisentraut wrote:

On 21.07.21 01:45, Alvaro Herrera wrote:

<screen>
-<userinput>gunzip postgresql-&version;.tar.gz</userinput>
-<userinput>tar xf postgresql-&version;.tar</userinput>
+<userinput>tar xfa postgresql-&version;.tar.gz</userinput>
</screen>

The "a" option only applies when creating a tar archive ("c" command). So
adding it here does nothing.

Oh, so the current `tar x` knows to uncompress the file without any
additional options? I've been pointlessly adding 'z', 'j', 'a' for years ...
That means we can remove the `gunzip` line and replace it with nothing.
WFM ...

--
Álvaro Herrera Valdivia, Chile — https://www.EnterpriseDB.com/
"But static content is just dynamic content that isn't moving!"
http://smylers.hates-software.com/2007/08/15/fe244d0c.html

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

Oh, so the current `tar x` knows to uncompress the file without any
additional options? I've been pointlessly adding 'z', 'j', 'a' for years ...

I wonder whether that's GNU-tar-specific. But we have GNU-isms
elsewhere, eg we removed references to "gmake" years ago. If someone
is dealing with a tar program that needs the extra option, they
probably know what to do.

That means we can remove the `gunzip` line and replace it with nothing.
WFM ...

WFM too. The other thing I wonder about is whether the example shouldn't
be assuming that you chose the .bz2 file instead of the .gz one.

regards, tom lane

On 2021-Jul-21, Tom Lane wrote:

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

That means we can remove the `gunzip` line and replace it with nothing.
WFM ...

WFM too. The other thing I wonder about is whether the example shouldn't
be assuming that you chose the .bz2 file instead of the .gz one.

Seems reasonable -- pushed with that last change.

Thanks!

--
Álvaro Herrera Valdivia, Chile — https://www.EnterpriseDB.com/

On 21.07.21 19:21, Alvaro Herrera wrote:

On 2021-Jul-21, Peter Eisentraut wrote:

On 21.07.21 01:45, Alvaro Herrera wrote:

<screen>
-<userinput>gunzip postgresql-&version;.tar.gz</userinput>
-<userinput>tar xf postgresql-&version;.tar</userinput>
+<userinput>tar xfa postgresql-&version;.tar.gz</userinput>
</screen>

The "a" option only applies when creating a tar archive ("c" command). So
adding it here does nothing.

Oh, so the current `tar x` knows to uncompress the file without any
additional options? I've been pointlessly adding 'z', 'j', 'a' for years ...
That means we can remove the `gunzip` line and replace it with nothing.

Unless you want to assume GNU tar, the gunzip is still necessary.

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

Seems reasonable -- pushed with that last change.

Hm ... actually, now that I read the committed patch, I realize that
it's effectively recommending that people build their installations
from the latest commit on master. That might be what aspiring PG
hackers want to do, but it's quite unlikely that Joe DBA wants to.
I think if we're going to recommend pulling the git repo as the
way to get the sources, we at least ought to recommend a
"git checkout REL_n_STABLE" step, and point out that this gives
you branch tip not a released-and-QAed version. On the whole though,
I'm having qualms about recommending this in this particular spot,
rather than back in Appendix I. Seems like the wrong audience is
going to be reading this chapter.

regards, tom lane

On 2021-Jul-21, Tom Lane wrote:

Hm ... actually, now that I read the committed patch, I realize that
it's effectively recommending that people build their installations
from the latest commit on master. That might be what aspiring PG
hackers want to do, but it's quite unlikely that Joe DBA wants to.
I think if we're going to recommend pulling the git repo as the
way to get the sources, we at least ought to recommend a
"git checkout REL_n_STABLE" step, and point out that this gives
you branch tip not a released-and-QAed version. On the whole though,
I'm having qualms about recommending this in this particular spot,
rather than back in Appendix I. Seems like the wrong audience is
going to be reading this chapter.

Well, we can remove that first paragraph from there and just refer the
reader to the appendix ... something like this, perhaps.

The appendix already has instructions on cloning the repo. It doesn't
say anything about branches though, but I'm not sure we want our docs to
become a tutorial on Git. We already link to git-scm.com though that's
not great; it doesn't explain our branch structure for example. We
could do better.

--
Álvaro Herrera Valdivia, Chile — https://www.EnterpriseDB.com/

Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:

On 21.07.21 19:21, Alvaro Herrera wrote:

Oh, so the current `tar x` knows to uncompress the file without any
additional options? I've been pointlessly adding 'z', 'j', 'a' for years ...
That means we can remove the `gunzip` line and replace it with nothing.

Unless you want to assume GNU tar, the gunzip is still necessary.

That seems overly conservative. On my Mac, Apple has kindly provided

$ tar --version
bsdtar 3.3.2 - libarchive 3.3.2 zlib/1.2.11 liblzma/5.0.5 bz2lib/1.0.6

and in case the mentioned libraries aren't enough clue, it does indeed
seem to work like GNU tar for this purpose:

$ tar tf postgresql-10.16.tar.bz2 | head -5
postgresql-10.16/
postgresql-10.16/.dir-locals.el
postgresql-10.16/contrib/
postgresql-10.16/contrib/tcn/
postgresql-10.16/contrib/tcn/tcn.control

A nearby FreeBSD box provides similar results. So the proposed
instructions probably work fine on most *BSD machines. I also
looked on Solaris 11, and here's what "man tar" has to say there:

j

c mode only. Compress the resulting archive with bzip2. In extract
or list modes, this option is ignored. The implementation recog-
nizes bzip2 compression type automatically when reading archives.
Upgrade/replace first decompresses and then applies the same mecha-
nism to compress the archive automatically.

I think this is another case of a GNUism that's become close
enough to universal that we don't need to be pedantic about it.

regards, tom lane

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

On 2021-Jul-21, Tom Lane wrote:

I'm having qualms about recommending this in this particular spot,
rather than back in Appendix I. Seems like the wrong audience is
going to be reading this chapter.

Well, we can remove that first paragraph from there and just refer the
reader to the appendix ... something like this, perhaps.

+1, though I think you're short a </para> or so.

The appendix already has instructions on cloning the repo. It doesn't
say anything about branches though, but I'm not sure we want our docs to
become a tutorial on Git. We already link to git-scm.com though that's
not great; it doesn't explain our branch structure for example. We
could do better.

Agreed that we're not here to teach people how to use git. But it'd
be worth explaining our branch naming conventions in that appendix.
It'd be sufficient I guess to mention "master" and "REL_n_STABLE";
by the time v15 sees the light of day, all the pre-v10 branches
will be EOL. (Maybe also explain the REL_m_n release tags?)

regards, tom lane

On 2021-Jul-21, Tom Lane wrote:

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

Well, we can remove that first paragraph from there and just refer the
reader to the appendix ... something like this, perhaps.

+1, though I think you're short a </para> or so.

Two markup errors actually, and there were a couple of other typos too.

Agreed that we're not here to teach people how to use git. But it'd
be worth explaining our branch naming conventions in that appendix.
It'd be sufficient I guess to mention "master" and "REL_n_STABLE";
by the time v15 sees the light of day, all the pre-v10 branches
will be EOL. (Maybe also explain the REL_m_n release tags?)

I'll leave that for another day.

--
Álvaro Herrera Valdivia, Chile — https://www.EnterpriseDB.com/
"Sallah, I said NO camels! That's FIVE camels; can't you count?"
(Indiana Jones)