Thread: New developer papercut - Makefile references INSTALL

Hello,

I encountered a minor road bump when checking out the pg source today. The Makefile's all target includes the following
helpmessage 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
snapshottarball. 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>" ; \

-Tim

> 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
followinghelp 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
snapshottarball. 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>" ; \

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
followinghelp 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
orsnapshot 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>" ; \
>
> 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
dependingon 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
containsthat 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

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
followinghelp 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
snapshottarball. 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>" ; \
>>
>> -Tim
>
>
> I noticed a similar thing in the README of the github repository. It asks to see the INSTALL file for build and
installationinstructions 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.

> Regards,
> Samay

=?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.

>                         regards, tom lane

=?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
https://www.postgresql.org/message-id/200403091751.i29HpiV24304%40candle.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

Hi,

On 2022-01-21 17:25:08 -0500, Tom Lane wrote:
> 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;

Hm, do we really want committers do that at any frequency? I think that
concern makes sense for contributors, but I think it's reasonable to expect
the docs to be built before committing changes.

It might be relevant that the dependencies for INSTALL generation are
considerably smaller than for a full docs build. It needs xsltproc, xmllint
and pandoc. Not tiny, but still a lot less than the full docbook toolchain.

On a debian container with just enough stuff installed to get through
./configure --without-readline --without-zlib (to minimize things installed
from another source):

apt-get install -y xsltproc libxml2-utils pandoc
...
The following NEW packages will be installed:
  libcmark-gfm-extensions0 libcmark-gfm0 libicu67 libxml2 libxml2-utils libxslt1.1 pandoc pandoc-data xsltproc
0 upgraded, 9 newly installed, 0 to remove and 0 not upgraded.
Need to get 28.8 MB of archives.
After this operation, 193 MB of additional disk space will be used.




Re committers, the biggest issue would presumably be working on windows :(. I
don't think the docs build is integrated into the msvc tooling right now.



> (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.)

Fair point, no idea how big that aspect is. I'd expect xsltproc to be halfway
OK in that regard, and it's certainly not changing much anymore. Pandoc, I
have no idea.


> 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.

It would. I guess it'd still be better than the situation today, but...

Greetings,

Andres Freund

On Fri, Jan 21, 2022 at 11:53 PM Andres Freund <andres@anarazel.de> wrote:
>
> Hi,
>
> On 2022-01-21 17:25:08 -0500, Tom Lane wrote:
> > 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.
>
> It would. I guess it'd still be better than the situation today, but...

post-commit hooks don't run on the git server, they run locally on
your machine. There is a "post receive" hook that runs on the git
server, but we definitely don't want that one to fabricate new commits
I think.

And it certainly cannot *modify* the commit that came in in flight, as
that would change the hash, and basically break the whole integrity of
the commit chain.

We could certainly have a cronjob somewhere that ran to check that
they were in sync and would auto-generate a patch if they weren't, for
a committer to review, but I'm not sure how much that would help?

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

Hi,

On 2022-02-09 22:32:59 +0100, Magnus Hagander wrote:
> On Fri, Jan 21, 2022 at 11:53 PM Andres Freund <andres@anarazel.de> wrote:
> > On 2022-01-21 17:25:08 -0500, Tom Lane wrote:
> > > 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.
> >
> > It would. I guess it'd still be better than the situation today, but...
> 
> post-commit hooks don't run on the git server, they run locally on
> your machine. There is a "post receive" hook that runs on the git
> server, but we definitely don't want that one to fabricate new commits
> I think.

Why not? We probably wouldn't want to do synchronously as part of the receive
hook, but if we have a policy that INSTALL is not to be updated by humans, but
updated automatically whenever its sources are modified, I'd be OK with
auto-committing that.


But before we go there, it might be worth checking if the generated INSTALL
actually changes meaningfully across "doc toolchain" versions. If not, a
simpler receive hook verifying that INSTALL was updated when the relevant sgml
files changed probably would be sufficient.

Greetings,

Andres Freund

Andres Freund <andres@anarazel.de> writes:
> On 2022-02-09 22:32:59 +0100, Magnus Hagander wrote:
>> post-commit hooks don't run on the git server, they run locally on
>> your machine. There is a "post receive" hook that runs on the git
>> server, but we definitely don't want that one to fabricate new commits
>> I think.

> Why not? We probably wouldn't want to do synchronously as part of the receive
> hook, but if we have a policy that INSTALL is not to be updated by humans, but
> updated automatically whenever its sources are modified, I'd be OK with
> auto-committing that.

What happens when the INSTALL build fails (which is quite possible,
I believe, even if a plain html build works)?

I don't really want any post-commit or post-receive hooks doing
anything interesting to the tree.  I think the odds for trouble
are significantly greater than any value we'd get out of it.

I'm in favor of unifying README and README.git along the lines
we discussed above.  I think that going further than that
will be a lot of trouble for very little gain; in fact no gain,
because I do not buy any of the arguments that have been
made about why changing the INSTALL setup would be beneficial.
If we adjust the README contents to be less confusing about that,
we're done.

            regards, tom lane

On Thu, Feb 10, 2022 at 12:52 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

(bringing this one back from the dead)



>
> Andres Freund <andres@anarazel.de> writes:
> > On 2022-02-09 22:32:59 +0100, Magnus Hagander wrote:
> >> post-commit hooks don't run on the git server, they run locally on
> >> your machine. There is a "post receive" hook that runs on the git
> >> server, but we definitely don't want that one to fabricate new commits
> >> I think.
>
> > Why not? We probably wouldn't want to do synchronously as part of the receive
> > hook, but if we have a policy that INSTALL is not to be updated by humans, but
> > updated automatically whenever its sources are modified, I'd be OK with
> > auto-committing that.

Auto committing in git becomes very.. Special. In that case you would
push but after that you would still not be in sync and have to pull
back down to compare.

It would also require the running of a comparatively very complex
build script inside the very restricted environment that is the git
master server. I do not want to have to deal with that level of
complexity there, and whatever security implications can come from it.

But if you want to accomplish something similar you could have a batch
job that runs on maybe a daily basis and builds the INSTALL file and
commits it to the repo. I still don't really like the idea of
committing automatically (in the github/gitlab world, having such a
tool generate a MR/PR would be perfectly fine, but pushing directly to
the repo I really prefer being something that has human eyes on the
process). Or post a patch with it for someone to look at.


> What happens when the INSTALL build fails (which is quite possible,
> I believe, even if a plain html build works)?

Yes, it breaks every time somebody accidentally puts a link to
somewhere else in the documentation, doesn't it?


> I don't really want any post-commit or post-receive hooks doing
> anything interesting to the tree.  I think the odds for trouble
> are significantly greater than any value we'd get out of it.

Very much agreed.


> I'm in favor of unifying README and README.git along the lines
> we discussed above.  I think that going further than that
> will be a lot of trouble for very little gain; in fact no gain,
> because I do not buy any of the arguments that have been
> made about why changing the INSTALL setup would be beneficial.
> If we adjust the README contents to be less confusing about that,
> we're done.

+1.

If anything, I'm more behind the idea of just getting rid of the
INSTALL file. A reference to the install instructions in the README
should be enough today. The likelihood of somebody getting a postgres
source tarball and trying to build it for the first time while not
having internet access is extremely low I'd say.

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

Magnus Hagander <magnus@hagander.net> writes:
> If anything, I'm more behind the idea of just getting rid of the
> INSTALL file. A reference to the install instructions in the README
> should be enough today. The likelihood of somebody getting a postgres
> source tarball and trying to build it for the first time while not
> having internet access is extremely low I'd say.

I agree that there's no longer a lot of reason to insist that the
installation instructions need to be present in a flat text file
as opposed to some other way.

However, just putting a URL into README seems problematic, because how
will we ensure that it's the correct version-specific URL?  (And it does
need to be version-specific; the set of configure options changes over
time, and that's not even mentioning whatever user-visible effects
changing to meson will have.)  You could imagine generating the URL
during tarball build, but that does nothing for the people who pull
directly from git.

I thought briefly about directing people to read
doc/src/sgml/html/installation.html, but that has the same problem
that it won't be present in a fresh git pull.

            regards, tom lane

On Mon, Mar 7, 2022 at 4:57 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Magnus Hagander <magnus@hagander.net> writes:
> > If anything, I'm more behind the idea of just getting rid of the
> > INSTALL file. A reference to the install instructions in the README
> > should be enough today. The likelihood of somebody getting a postgres
> > source tarball and trying to build it for the first time while not
> > having internet access is extremely low I'd say.
>
> I agree that there's no longer a lot of reason to insist that the
> installation instructions need to be present in a flat text file
> as opposed to some other way.
>
> However, just putting a URL into README seems problematic, because how
> will we ensure that it's the correct version-specific URL?  (And it does
> need to be version-specific; the set of configure options changes over
> time, and that's not even mentioning whatever user-visible effects
> changing to meson will have.)  You could imagine generating the URL
> during tarball build, but that does nothing for the people who pull
> directly from git.
>
> I thought briefly about directing people to read
> doc/src/sgml/html/installation.html, but that has the same problem
> that it won't be present in a fresh git pull.

Yeah, if we just care about tarballs that works, but then it also
works to inject the version number in the README file.

But taking a step back, who is the actual audience for this? Do we
*need* a link pointing directly there, or is it enough to just point
to "use the docs on the web"? We can't link to the incorrect version,
but can we just link to /docs/ and leave it at that?

If not, could we make the change of URL a part of the branching step?
Branch to a stable release would the include modifying README, and be
mad ea step of version_stamp.pl?

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

Magnus Hagander <magnus@hagander.net> writes:
> But taking a step back, who is the actual audience for this? Do we
> *need* a link pointing directly there, or is it enough to just point
> to "use the docs on the web"? We can't link to the incorrect version,
> but can we just link to /docs/ and leave it at that?

Well, it's people compiling from source, so I guess we can assume some
amount of cluefulness?  I think perhaps it'd be okay to say "go here
and then navigate to the proper sub-page for your version".

> If not, could we make the change of URL a part of the branching step?
> Branch to a stable release would the include modifying README, and be
> mad ea step of version_stamp.pl?

Doesn't really help people working from git, I think, because the
master branch is always going to claim to be "devel" even when you
rewind it to some old state.  Maybe we can assume people doing
such a thing have even more clue ... but on the whole I'd rather
not add the additional complication.

            regards, tom lane

On Mon, Mar 7, 2022 at 5:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Magnus Hagander <magnus@hagander.net> writes:
> > But taking a step back, who is the actual audience for this? Do we
> > *need* a link pointing directly there, or is it enough to just point
> > to "use the docs on the web"? We can't link to the incorrect version,
> > but can we just link to /docs/ and leave it at that?
>
> Well, it's people compiling from source, so I guess we can assume some
> amount of cluefulness?  I think perhaps it'd be okay to say "go here
> and then navigate to the proper sub-page for your version".

It's kind of hard for me to imagine that not being enough for somebody.

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

On Mon, Mar 7, 2022 at 11:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Magnus Hagander <magnus@hagander.net> writes:
> > But taking a step back, who is the actual audience for this? Do we
> > *need* a link pointing directly there, or is it enough to just point
> > to "use the docs on the web"? We can't link to the incorrect version,
> > but can we just link to /docs/ and leave it at that?
>
> Well, it's people compiling from source, so I guess we can assume some
> amount of cluefulness?  I think perhaps it'd be okay to say "go here
> and then navigate to the proper sub-page for your version".
>
> > If not, could we make the change of URL a part of the branching step?
> > Branch to a stable release would the include modifying README, and be
> > mad ea step of version_stamp.pl?
>
> Doesn't really help people working from git, I think, because the
> master branch is always going to claim to be "devel" even when you
> rewind it to some old state.  Maybe we can assume people doing
> such a thing have even more clue ... but on the whole I'd rather
> not add the additional complication.

Well it could per major version couldn't it? When we start working on
v16, we stamp master as that, and we could use that for the links. It
will work "for the past", but if will of course not be able to track
how the docs changes between the individual commits -- since our
website only has the latest release for each one. If we need that it
needs to be in the source tree -- but is that actually a requirement?

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

Magnus Hagander <magnus@hagander.net> writes:
> On Mon, Mar 7, 2022 at 11:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Doesn't really help people working from git, I think, because the
>> master branch is always going to claim to be "devel" even when you
>> rewind it to some old state.  Maybe we can assume people doing
>> such a thing have even more clue ... but on the whole I'd rather
>> not add the additional complication.

> Well it could per major version couldn't it? When we start working on
> v16, we stamp master as that, and we could use that for the links. It
> will work "for the past", but if will of course not be able to track
> how the docs changes between the individual commits -- since our
> website only has the latest release for each one. If we need that it
> needs to be in the source tree -- but is that actually a requirement?

I think that adds more complication than usefulness.  ISTM having the
master branch not identify itself more specifically than "devel" is
actually a good thing in this context, for precisely the reason that
the corresponding docs are likely to be in flux.  Seeing "v16" seems
likely to lull people into a false sense of certainty that whatever
they find on the web matches the code they actually have.

So I'm coming to the position that the README file ought not contain
any link more specific than https://www.postgresql.org/docs/
and that it should then tell you to look at the installation chapters
in the appropriate version's docs.  (Considering we have multiple
installation chapters nowadays, we couldn't provide an exact URL
anyway.)

            regards, tom lane