Thread

Commits

Rework installation instructions again
- 73c5d2bfee29 15.0 landed
Improve installation instructions a bit
- aaec237b1a2f 15.0 landed

Link t the souce code

Daniel Westermann (DWE) <daniel.westermann@dbi-services.com> — 2021-05-04T18:50:37Z

Hi,

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. 

Thoughts?

Regards,
Daniel

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-05-06T21:53:36Z

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

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-05-06T22:05:45Z

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

Re: Link t the souce code

Jonathan S. Katz <jkatz@postgresql.org> — 2021-05-06T22:06:56Z

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

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-05-06T23:22:43Z

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

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-05-06T23:30:20Z

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

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-07-20T23:45:55Z

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/

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-07-21T00:09:04Z

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

Re: Link t the souce code

Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-07-21T15:27:42Z

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.

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-07-21T17:21:07Z

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

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-07-21T17:42:54Z

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

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-07-21T17:58:58Z

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/

Re: Link t the souce code

Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2021-07-21T18:09:00Z

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.

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-07-21T18:14:23Z

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

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-07-21T18:24:42Z

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/

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-07-21T18:36:49Z

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

Re: Link t the souce code

Tom Lane <tgl@sss.pgh.pa.us> — 2021-07-21T18:51:38Z

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

Re: Link t the souce code

Alvaro Herrera <alvherre@alvh.no-ip.org> — 2021-07-22T22:14:58Z

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)