New developer papercut - Makefile references INSTALL

On 17 Jan 2022, at 02:11, Tim McNamara <tim@mcnamara.nz> wrote:

Hello,

I encountered a minor road bump when checking out the pg source today. The Makefile's all target includes the following help message if GNUmakefile isn't available:

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions." ; \

After consulting README.git, it looks as though INSTALL isn't created unless the source is bundled into a release or snapshot tarball. I'm happy to submit a patch to update the wording, but wanted to check on the preferred approach.

Perhaps this would be sufficient?

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions, or visit" ; \
echo "<https://www.postgresql.org/docs/devel/installation.html&gt;&quot; ; \

That's a good point, and one few developers are likely to spot so thanks for
raising the issue. To avoid replicating the wording we can do something like
the attached as well.

--
Daniel Gustafsson https://vmware.com/

On Mon, Jan 17, 2022 at 11:17 AM Daniel Gustafsson <daniel@yesql.se> wrote:

On 17 Jan 2022, at 02:11, Tim McNamara <tim@mcnamara.nz> wrote:

Hello,

I encountered a minor road bump when checking out the pg source today. The Makefile's all target includes the following help message if GNUmakefile isn't available:

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions." ; \

After consulting README.git, it looks as though INSTALL isn't created unless the source is bundled into a release or snapshot tarball. I'm happy to submit a patch to update the wording, but wanted to check on the preferred approach.

Perhaps this would be sufficient?

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions, or visit" ; \
echo "<https://www.postgresql.org/docs/devel/installation.html&gt;&quot; ; \

That's a good point, and one few developers are likely to spot so thanks for
raising the issue. To avoid replicating the wording we can do something like
the attached as well.

Nitpick: It reads very strange to do the existence check negative.
Since you're filling a value in both the positive and negative branch
it seems more logical with an "if -f" and then reversed order of the
branches.

That said, I'm not sure we're actually gaining anything by *not*
referring to the website as well. TBH, I bet the majority of users
will actually prefer to read them there. So I'd suggest always
including the reference to the website as well, per the suggestion
from Tim.

--
Magnus Hagander
Me: https://www.hagander.net/
Work: https://www.redpill-linpro.com/

On 17 Jan 2022, at 11:25, Magnus Hagander <magnus@hagander.net> wrote:

That said, I'm not sure we're actually gaining anything by *not*
referring to the website as well. TBH, I bet the majority of users
will actually prefer to read them there. So I'd suggest always
including the reference to the website as well, per the suggestion
from Tim.

Fair point, I'll go ahead and do that in a bit unless anyone objects.

--
Daniel Gustafsson https://vmware.com/

On 17 Jan 2022, at 13:26, Daniel Gustafsson <daniel@yesql.se> wrote:

On 17 Jan 2022, at 11:25, Magnus Hagander <magnus@hagander.net> wrote:

That said, I'm not sure we're actually gaining anything by *not*
referring to the website as well. TBH, I bet the majority of users
will actually prefer to read them there. So I'd suggest always
including the reference to the website as well, per the suggestion
from Tim.

Fair point, I'll go ahead and do that in a bit unless anyone objects.

I plan on applying the attached which address the feedback given.

--
Daniel Gustafsson https://vmware.com/

On 18.01.22 16:51, Daniel Gustafsson wrote:

On 17 Jan 2022, at 13:26, Daniel Gustafsson <daniel@yesql.se> wrote:

On 17 Jan 2022, at 11:25, Magnus Hagander <magnus@hagander.net> wrote:

That said, I'm not sure we're actually gaining anything by *not*
referring to the website as well. TBH, I bet the majority of users
will actually prefer to read them there. So I'd suggest always
including the reference to the website as well, per the suggestion
from Tim.

Fair point, I'll go ahead and do that in a bit unless anyone objects.

I plan on applying the attached which address the feedback given.

The indentation of the two INSTRUCTIONS= lines uses a different mix of
tabs and spaces, so it looks a bit weird depending on how you view it.

It's also a bit strange that the single quotes are part of the value of
$INSTRUCTIONS rather than part of the fixed text.

The URL links to the "devel" version of the installation instructions,
which will not remain appropriate after release. I don't know how to
fix that without creating an additional maintenance point. Since
README.git already contains that link, I would leave off the web site
business and just make the change of the dynamically chosen file name.

Daniel Gustafsson <daniel@yesql.se> writes:

I plan on applying the attached which address the feedback given.

+1

regards, tom lane

On 18 Jan 2022, at 17:05, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
On 18.01.22 16:51, Daniel Gustafsson wrote:

I plan on applying the attached which address the feedback given.

The indentation of the two INSTRUCTIONS= lines uses a different mix of tabs and spaces, so it looks a bit weird depending on how you view it.

It's also a bit strange that the single quotes are part of the value of $INSTRUCTIONS rather than part of the fixed text.

Fixed both of these, thanks!

The URL links to the "devel" version of the installation instructions, which will not remain appropriate after release. I don't know how to fix that without creating an additional maintenance point. Since README.git already contains that link, I would leave off the web site business and just make the change of the dynamically chosen file name.

I ended up pushing this with the URL in place as there IMO was consensus in the
thread for including it. We could if we want to update it to point to v15 docs
once we branch off, but anything more than that is probably in the diminishing
returns territory in terms of effort involved.

--
Daniel Gustafsson https://vmware.com/

Daniel Gustafsson <daniel@yesql.se> writes:

I ended up pushing this with the URL in place as there IMO was consensus in the
thread for including it. We could if we want to update it to point to v15 docs
once we branch off, but anything more than that is probably in the diminishing
returns territory in terms of effort involved.

I think pointing at devel is fine, since this text is mostly aimed
at developers or would-be developers anyway.

regards, tom lane

On Wed, Jan 19, 2022 at 4:58 PM Tim McNamara <tim@mcnamara.nz> wrote:

Hello,

I encountered a minor road bump when checking out the pg source today. The
Makefile's all target includes the following help message if GNUmakefile
isn't available:

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions." ; \

After consulting README.git, it looks as though INSTALL isn't created
unless the source is bundled into a release or snapshot tarball. I'm happy
to submit a patch to update the wording, but wanted to check on the
preferred approach.

Perhaps this would be sufficient?

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions, or visit" ; \
echo "<https://www.postgresql.org/docs/devel/installation.html&gt;&quot; ; \

-Tim

I noticed a similar thing in the README of the github repository. It asks
to see the INSTALL file for build and installation instructions but I
couldn't find that file and that confused me. This might confuse other new
developers as well. So, maybe we should update the text in the README too?

Regards,
Samay

pá 21. 1. 2022 v 1:29 odesílatel samay sharma <smilingsamay@gmail.com> napsal:

On Wed, Jan 19, 2022 at 4:58 PM Tim McNamara <tim@mcnamara.nz> wrote:

Hello,

I encountered a minor road bump when checking out the pg source today. The Makefile's all target includes the following help message if GNUmakefile isn't available:

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions." ; \

After consulting README.git, it looks as though INSTALL isn't created unless the source is bundled into a release or snapshot tarball. I'm happy to submit a patch to update the wording, but wanted to check on the preferred approach.

Perhaps this would be sufficient?

echo "You need to run the 'configure' program first. See the file"; \
echo "'INSTALL' for installation instructions, or visit" ; \
echo "<https://www.postgresql.org/docs/devel/installation.html&gt;&quot; ; \

-Tim

I noticed a similar thing in the README of the github repository. It asks to see the INSTALL file for build and installation instructions but I couldn't find that file and that confused me. This might confuse other new developers as well. So, maybe we should update the text in the README too?

There is README.git explaining this. README itself is meant to be used
for distributed source code. You can generate INSTALL locally for
example by running make dist (INSTALL will be present in
postgresql-15devel directory).

Anyway I do agree this is confusing. Maybe we can actually rename
README.git to README and current README to README.dist or similar.
README.dist can be copied to distribution package as README during
Makefile magic.

I can try to provide a patch if welcomed.

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:

There is README.git explaining this. README itself is meant to be used
for distributed source code. You can generate INSTALL locally for
example by running make dist (INSTALL will be present in
postgresql-15devel directory).

Anyway I do agree this is confusing. Maybe we can actually rename
README.git to README and current README to README.dist or similar.
README.dist can be copied to distribution package as README during
Makefile magic.

IIRC, we discussed that when README.git was invented, and concluded
that it would just create different sorts of confusion. I might
be biased, as the person who is generally checking created tarballs
for sanity, but I really do not want any situation where a file
appearing in the tarball is different from the same-named file in
the git tree.

Perhaps it could be sane to not have *any* file named README in
the git tree, only README.git and README.dist, with the tarball
preparation process copying README.dist to README. However,
if I'm understanding what github does, that would leave us with
no automatically-displayed documentation for the github repo.
So I'm not sure that helps with samay's concern.

regards, tom lane

pá 21. 1. 2022 v 16:31 odesílatel Tom Lane <tgl@sss.pgh.pa.us> napsal:

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:

There is README.git explaining this. README itself is meant to be used
for distributed source code. You can generate INSTALL locally for
example by running make dist (INSTALL will be present in
postgresql-15devel directory).

Anyway I do agree this is confusing. Maybe we can actually rename
README.git to README and current README to README.dist or similar.
README.dist can be copied to distribution package as README during
Makefile magic.

IIRC, we discussed that when README.git was invented, and concluded
that it would just create different sorts of confusion. I might
be biased, as the person who is generally checking created tarballs
for sanity, but I really do not want any situation where a file
appearing in the tarball is different from the same-named file in
the git tree.

Perhaps it could be sane to not have *any* file named README in
the git tree, only README.git and README.dist, with the tarball
preparation process copying README.dist to README. However,
if I'm understanding what github does, that would leave us with
no automatically-displayed documentation for the github repo.
So I'm not sure that helps with samay's concern.

Especially for GitHub use-case it is possible to add separate readme
into .github directory. But the problem with local clone will not be
solved anyway.

From GitHub docs:

"If you put your README file in your repository's root, docs, or
hidden .github directory, GitHub will recognize and automatically
surface your README to repository visitors."

Another solution would be to merge both README files together and make
separate section for development/git based codebase.

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:

Another solution would be to merge both README files together and make
separate section for development/git based codebase.

There's a lot to be said for that approach: make it simpler, not
more complicated.

regards, tom lane

On Fri, Jan 21, 2022 at 11:39 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:

Another solution would be to merge both README files together and make
separate section for development/git based codebase.

There's a lot to be said for that approach: make it simpler, not
more complicated.

Yeah. And what about just getting rid of the INSTALL file altogether?
I think that, in 2022, a lot of people are likely to use git to obtain
the source code rather than obtain a tarball. And regardless of what
method they use to get the source code, they don't really need there
to be a text file in the directory with installation instructions; a
URL is just fine. There was a time when you couldn't count on people
to have a web browser conveniently available, either because that
whole world wide web thing hadn't really caught on yet, or because
they didn't even have an always-on Internet connection. In that world,
an INSTALL file in the tarball makes a lot of sense. But these delays,
the number of people who are still obtaining PostgreSQL via
UUCP-over-modem-relay has got to be ... relatively limited.

--
Robert Haas
EDB: http://www.enterprisedb.com

Robert Haas <robertmhaas@gmail.com> writes:

On Fri, Jan 21, 2022 at 11:39 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:

Another solution would be to merge both README files together and make
separate section for development/git based codebase.

There's a lot to be said for that approach: make it simpler, not
more complicated.

Yeah.

Josef, you want to draft a patch?

And what about just getting rid of the INSTALL file altogether?
I think that, in 2022, a lot of people are likely to use git to obtain
the source code rather than obtain a tarball. And regardless of what
method they use to get the source code, they don't really need there
to be a text file in the directory with installation instructions; a
URL is just fine. There was a time when you couldn't count on people
to have a web browser conveniently available, either because that
whole world wide web thing hadn't really caught on yet, or because
they didn't even have an always-on Internet connection. In that world,
an INSTALL file in the tarball makes a lot of sense. But these delays,
the number of people who are still obtaining PostgreSQL via
UUCP-over-modem-relay has got to be ... relatively limited.

I'm not convinced by this argument. In the first place, the INSTALL
file isn't doing any harm. I don't know that I'd bother to build the
infrastructure for it today, but we already have that infrastructure
and it's not causing us any particular maintenance burden. In the
second place, I think your argument is a bit backwards. Sure, people
who are relying on a git pull can be expected to have easy access to
on-line docs; that's exactly why we aren't troubled by not providing
ready-to-go INSTALL docs in that case. But that doesn't follow for
people who are using a tarball. In particular, it might not be that
easy to find on-line docs matching the specific tarball version they
are working with. (With the planned meson conversion, that's about to
become a bigger deal than it's been in the recent past.)

regards, tom lane

On Fri, Jan 21, 2022 at 12:19 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

I'm not convinced by this argument. In the first place, the INSTALL
file isn't doing any harm. I don't know that I'd bother to build the
infrastructure for it today, but we already have that infrastructure
and it's not causing us any particular maintenance burden.

I think it *is* doing harm. It confuses people. We get semi-regular
threads on the list like this one where people are confused by the
file not being there, but I can't remember ever seeing a thread where
someone said that it was great, or said that they thought it needed
improvement, or said that they used it and then something interesting
happened afterward, or anything like that. AFAICR, the only threads on
the mailing list that mention the file at all are started by people
who were told to look there and couldn't find the file. Now we can
speculate that there is a far larger number of people who find the
file, love it, and have no problems with it or suggestions for
improvement or need to comment upon it in any way, and that's hard to
disprove. But I doubt it.

In the
second place, I think your argument is a bit backwards. Sure, people
who are relying on a git pull can be expected to have easy access to
on-line docs; that's exactly why we aren't troubled by not providing
ready-to-go INSTALL docs in that case. But that doesn't follow for
people who are using a tarball. In particular, it might not be that
easy to find on-line docs matching the specific tarball version they
are working with. (With the planned meson conversion, that's about to
become a bigger deal than it's been in the recent past.)

I would guess that these days if you're brave enough to compile from
source, you are very, very likely to get that source from git rather
than a tarball. These days if you Google "[name of any piece of
software] source code" the first hit is the git repository. I grant
that the second hit, in the case of PostgreSQL, is a link to download
page for tarballs, but when I try plugging other things in there
instead of "postgresql" the git repository is always the first hit,
and sometimes there's a download page after that. Again, this doesn't
prove anything, but I do think it's suggestive.

--
Robert Haas
EDB: http://www.enterprisedb.com

Robert Haas <robertmhaas@gmail.com> writes:

On Fri, Jan 21, 2022 at 12:19 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

I'm not convinced by this argument. In the first place, the INSTALL
file isn't doing any harm. I don't know that I'd bother to build the
infrastructure for it today, but we already have that infrastructure
and it's not causing us any particular maintenance burden.

I think it *is* doing harm. It confuses people. We get semi-regular
threads on the list like this one where people are confused by the
file not being there,

That's not the fault of INSTALL, that's the fault of the README files,
which I think we're agreed we can fix. (Or, if you suppose that they
came to the code with some previous expectation that there'd be an
INSTALL file, taking it away is certainly not going to improve matters.)

but I can't remember ever seeing a thread where
someone said that it was great, or said that they thought it needed
improvement, or said that they used it and then something interesting
happened afterward, or anything like that.

It's just another copy of the same documentation, so I can't really
imagine a situation where someone would feel a need to mention it
specifically.

regards, tom lane

Hi,

On 2022-01-21 11:49:12 -0500, Robert Haas wrote:

On Fri, Jan 21, 2022 at 11:39 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:

Another solution would be to merge both README files together and make
separate section for development/git based codebase.

There's a lot to be said for that approach: make it simpler, not
more complicated.

I agree, that's the right direction.

Yeah. And what about just getting rid of the INSTALL file altogether?

Yea, I think that might be worth doing too, at least in some form. It's
certainly not helpful to have it in the tarball but not the git tree.

I tried to find the discussion around removing INSTALL from the source tree,
but it seems to actually have centered much more around HISTORY
/messages/by-id/200403091751.i29HpiV24304@candle.pha.pa.us

It seems quite workable to continue for INSTALL to be generated, but have the
result checked in. The rate of changes to {installation,install-windows}.sgml
isn't that high, and when things change, it's actually useful to be able to
see the current instructions from a console.

Might even be good to be forced to see the text version of INSTALL when
changing the sgml docs...

I think that, in 2022, a lot of people are likely to use git to obtain
the source code rather than obtain a tarball.

Indeed.

And regardless of what method they use to get the source code, they don't
really need there to be a text file in the directory with installation
instructions; a URL is just fine.

Even working with git trees, I do quite prefer having the instructions
available in a terminal compatible way, TBH. The building happens in a
terminal, after all. In our case it's made worse by the browser version being
split across ~10 pages and multiple chapters.

There was a time when you couldn't count on people to have a web browser
conveniently available, either because that whole world wide web thing
hadn't really caught on yet, or because they didn't even have an always-on
Internet connection. In that world, an INSTALL file in the tarball makes a
lot of sense. But these delays, the number of people who are still obtaining
PostgreSQL via UUCP-over-modem-relay has got to be ... relatively limited.

There's still people having to build postgres on systems without internet
access - but typically they'll have access to the instructions when developin
the scripts for that...

Greetings,

Andres Freund

Andres Freund <andres@anarazel.de> writes:

It seems quite workable to continue for INSTALL to be generated, but have the
result checked in. The rate of changes to {installation,install-windows}.sgml
isn't that high, and when things change, it's actually useful to be able to
see the current instructions from a console.
Might even be good to be forced to see the text version of INSTALL when
changing the sgml docs...

Not sure about that, because

(1) if done wrong, it'd make it impossible to commit into the
docs unless you have a working docs toolchain on your machine,
whether you wanted to touch installation.sgml or not;

(2) we'd inevitably get a lot of diff noise because of different
committers having different versions of the docs toolchain.
(Unlike configure, trying to require uniformity of those tools
seems quite impractical.)

Perhaps this could be finessed by making updating of INSTALL
the responsibility of some post-commit hook on the git server.
Not sure that we want to go there, though. In any case, that
approach would negate your point about seeing the results.

regards, tom lane