Re: INSTALL file

* Andreas 'ads' Scherbaum (ads(at)pgug(dot)de) wrote:
> On 30.10.18 11:49, Andrew Dunstan wrote:
> >On 10/30/2018 06:14 AM, Andreas 'ads' Scherbaum wrote:
> >>On 30.10.18 04:11, Michael Paquier wrote:
> >>>FWIW, I think that people depend too much on github and what github
> >>>thinks projects should do to be more presentable, like adding a
> >>>markdown-style README or such.

I don't find this to be all that relevant- people clone our git repo all
the time and cloning it either directly or through one of the mirrors is
almost certainly what people interested in working with the source code
will do first, these days.

For better or worse, the days of people pulling down tarballs to start
hacking on code are pretty much gone. We likely still need to provide
the tarballs for our packagers, but that may be gone one day too.

> >>>I get your point that people look at README first though, and that the
> >>>current status is confusing.  One idea would be to merge the contents
> >>>of
> >>>README.git into the README.  However the current status also makes some
> >>>sense, as INSTALL is part of an distributed tarball, while README.git
> >>>is
> >>>automatically removed when running "make distdir".  Looking at README
> >>>is
> >>>the first thing I do when checking out any project or after
> >>>decompressing any source code tarball, so things could be better.

The current status is confusing and does *not* make sense today. The
README needs to be updated to be sensible to someone using git to pull
down the repo. The only way to make the current approach make sense
would be to actually *remove* the currently confusing README from the
git repo in its current form and also generate it as part of the tarball
build, but that seems like it's going very much in the wrong direction.

> >>Right, thanks. That's why one of my proposals was to have an INSTALL
> >>file in place, and overwrite it during the tarball creation process.
> >>
> >>This way the general INSTALL file is there, and can contain "general"
> >>instructions, and later on is overwritten by a specific INSTALL file for
> >>the tarballs.

I'm not really much of a fan of this. My thinking would be to merge the
README.git into the README, and, in particular, provide a very clear
link to the
https://www.postgresql.org/docs/devel/static/installation.html URL. I'd
also be a fan of including the 'Short version' in the README, and/or
maybe instructions on how to build the INSTALL file, but I suspect that
to be non-trivial to someone new.

> >That has the potential to be somewhat confusing:
> >
> >   "The INSTALL file says ..."
> >
> >   "Which INSTALL file are you referring to?"
> >
> >
> >Merging README.git into README make sense.

Agreed.

> >I think our attitude has generally been that if you're a developer you
> >should build from git, in which case we assume you know what you're doing,
> >and everyone else should build from a tarball. That's arguably somewhat
> >old-fashioned, specially since you can download release tarballs/zips from
> >places like <https://github.com/postgres/postgres/releases> Sadly, these
> >won't have the artefacts created by "make dist". Maybe those too are less
> >important these days.

This is more than 'old fashioned', in my view, it's just not what
happens today. Unfortunately, I don't think we have the stats anymore,
but I strongly suspect that our github/git/git mirrors get far more
pulls than our tarballs do now.

> Most experienced developers will know, I think. This was raised during the
> Google Code-In project, where students stumbled over this, and asked where
> the INSTALL file is ...
>
> This has potential to confuse anyone new to PostgreSQL, and it's a burden
> which can easily be avoided.

Agreed, we should really improve the README by merging the README.git
into it and make the project, as a whole, more accessible to new
developers.

Thanks!

Stephen