Обсуждение: INSTALL file

On 10/28/2018 08:13 AM, Andreas 'ads' Scherbaum wrote:
>
> Hello,
>
> while working with Google Code-In students, there is one task: "clone 
> PostgreSQL from git repository, and build from source".
>
> This brought up an interesting problem: the README refers to an 
> "INSTALL" file, which is present in packages, but not in the source 
> repo. This is very confusing for beginners, and should be avoided.
>
> There are a couple options to fix this:
>
>  1. Update the README, and remove the "INSTALL" reference
>  2. Create a permanent INSTALL file, and possibly overwrite it during
>     packaging
>  3. Add different INSTALL files, based on the platform (Linux, BSD,
>     Windows, Source)
>
>
> Regards,
>
>



See README.git

cheers

andrew

-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On 28.10.18 20:39, Andrew Dunstan wrote:
>
>
> On 10/28/2018 08:13 AM, Andreas 'ads' Scherbaum wrote:
>>
>> Hello,
>>
>> while working with Google Code-In students, there is one task: "clone
>> PostgreSQL from git repository, and build from source".
>>
>> This brought up an interesting problem: the README refers to an
>> "INSTALL" file, which is present in packages, but not in the source
>> repo. This is very confusing for beginners, and should be avoided.
>>
>> There are a couple options to fix this:
>>
>>  1. Update the README, and remove the "INSTALL" reference
>>  2. Create a permanent INSTALL file, and possibly overwrite it during
>>     packaging
>>  3. Add different INSTALL files, based on the platform (Linux, BSD,
>>     Windows, Source)
>>
>>
>> Regards,
>>
>>
>
>
>
> See README.git


That is not the first file people looking at. Especially not people
looking at the GitHub copy:


https://github.com/postgres/postgres


I understand that there is documentation, but for the casual developer
looking at this, it seems broken.


Regards,

--
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum wrote:
> That is not the first file people looking at. Especially not people looking
> at the GitHub copy:
>
> https://github.com/postgres/postgres
>
> I understand that there is documentation, but for the casual developer
> looking at this, it seems broken.

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

On 30.10.18 04:11, Michael Paquier wrote:
> On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum wrote:
>> That is not the first file people looking at. Especially not people looking
>> at the GitHub copy:
>>
>> https://github.com/postgres/postgres
>>
>> I understand that there is documentation, but for the casual developer
>> looking at this, it seems broken.
> 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 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.


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.


Regards,

-- 

                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On 10/30/2018 06:14 AM, Andreas 'ads' Scherbaum wrote:
> On 30.10.18 04:11, Michael Paquier wrote:
>> On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum wrote:
>>> That is not the first file people looking at. Especially not people 
>>> looking
>>> at the GitHub copy:
>>>
>>> https://github.com/postgres/postgres
>>>
>>> I understand that there is documentation, but for the casual developer
>>> looking at this, it seems broken.
>> 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 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.
>
>
> 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.
>
>
>



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.

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.

cheers

andrew

-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

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:
>>> On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum
>>> wrote:
>>>> That is not the first file people looking at. Especially not people
>>>> looking
>>>> at the GitHub copy:
>>>>
>>>> https://github.com/postgres/postgres
>>>>
>>>> I understand that there is documentation, but for the casual developer
>>>> looking at this, it seems broken.
>>> 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 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.
>>
>>
>> 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.
>>
>>
>>
>
>
>
> 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.
>
> 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.
>

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.


--
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

* Andreas 'ads' Scherbaum (ads@pgug.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

On Wed, Oct 31, 2018 at 08:30:40AM -0400, Stephen Frost wrote:
> 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.

+1.  I think as well that this approach would be a good thing.
--
Michael

Hi,

On 2018-11-01 09:29:37 +0900, Michael Paquier wrote:
> On Wed, Oct 31, 2018 at 08:30:40AM -0400, Stephen Frost wrote:
> > 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.
> 
> +1.  I think as well that this approach would be a good thing.

Strong +1.  I was recently looking through the information for new
developers and it's a major mess.

Greetings,

Andres Freund

On 01.11.18 01:29, Michael Paquier wrote:
> On Wed, Oct 31, 2018 at 08:30:40AM -0400, Stephen Frost wrote:
>> 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.
> +1.  I think as well that this approach would be a good thing.


Picking up on this idea, attached is a first draft for changing the README.

It includes links to the website, as well as the short version of the 
installation instructions.


Regards,

-- 
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On Thu, Nov 01, 2018 at 01:32:09AM +0100, Andreas 'ads' Scherbaum wrote:
> Picking up on this idea, attached is a first draft for changing the
> README.

Why don't you add it to the upcoming commit fest?  It would be good to
get some traction with a formal review.

> It includes links to the website, as well as the short version of the
> installation instructions.

+The installation instructions are listed on the website:
+
+https://www.postgresql.org/docs/current/static/install-short.html
+
+Short version:
+
+./configure
+make
+su
+make install
+adduser postgres
+mkdir /usr/local/pgsql/data
+chown postgres /usr/local/pgsql/data
+su - postgres
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start

Adding a section about installation and another one about documentation
are good things.  Now for the installation section I disagree about
adding this detailed way of doing things, and just adding a URL looks
enough.

Pointing to the global installation recommendations would be a better
fit also as a lot of things are platform-dependent.  So this URL looks
better:
https://www.postgresql.org/docs/current/static/installation.html

Now there is also a problem, the README would point out to the
development version of the documentation.  As this is made at working
using git, I could personally live with having stable branches also
refer to the development version, but it could also make sense to have
each stable branch point to the URL of the versions they work on.
--
Michael

On 01.11.18 07:26, Michael Paquier wrote:
> On Thu, Nov 01, 2018 at 01:32:09AM +0100, Andreas 'ads' Scherbaum wrote:
>> Picking up on this idea, attached is a first draft for changing the
>> README.
> Why don't you add it to the upcoming commit fest?  It would be good to
> get some traction with a formal review.

I plan to do that, once I gathered some feedback here.


>> It includes links to the website, as well as the short version of the
>> installation instructions.
> +The installation instructions are listed on the website:
> +
> +https://www.postgresql.org/docs/current/static/install-short.html
> +
> +Short version:
> +
> +./configure
> +make
> +su
> +make install
> +adduser postgres
> +mkdir /usr/local/pgsql/data
> +chown postgres /usr/local/pgsql/data
> +su - postgres
> +/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
> +/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
>
> Adding a section about installation and another one about documentation
> are good things.  Now for the installation section I disagree about
> adding this detailed way of doing things, and just adding a URL looks
> enough.
Was thinking about this, but then decided to add it as an example,
and see what people think.


>
> Pointing to the global installation recommendations would be a better
> fit also as a lot of things are platform-dependent.  So this URL looks
> better:
> https://www.postgresql.org/docs/current/static/installation.html
>
> Now there is also a problem, the README would point out to the
> development version of the documentation.  As this is made at working
> using git, I could personally live with having stable branches also
> refer to the development version, but it could also make sense to have
> each stable branch point to the URL of the versions they work on.

That is a bit problematic. The README lives on git first, and therefore
should point to the development version. The release process
can replace this with links to the current version.


Regards,

-- 
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

Greetings,

* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
> On 01.11.18 07:26, Michael Paquier wrote:
> >>It includes links to the website, as well as the short version of the
> >>installation instructions.
> >+The installation instructions are listed on the website:
> >+
> >+https://www.postgresql.org/docs/current/static/install-short.html

I don't think we should link to the "Short version" directly here, the
above URL should be the "installation.html" one..  With a caveat, see
below.

> >+Short version:
> >+
> >+./configure
> >+make
> >+su
> >+make install
> >+adduser postgres
> >+mkdir /usr/local/pgsql/data
> >+chown postgres /usr/local/pgsql/data
> >+su - postgres
> >+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
> >+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
> >
> >Adding a section about installation and another one about documentation
> >are good things.  Now for the installation section I disagree about
> >adding this detailed way of doing things, and just adding a URL looks
> >enough.
> Was thinking about this, but then decided to add it as an example,
> and see what people think.

I like having the detail, but I'd go farther, really.  Here's my
thinking:

BUILDING ON UNIX
====================

Detailed instructions for many Unix platforms is available here:
https://www.postgresql.org/docs/current/static/installation.html

To build PostgreSQL on most Unix variants, the following are required:

GNU make, version 3.8 or newer
ISO/ANSI C compilar (at least C99-compliant)
Flex 2.5.31 or later, and Bison 1.875 or later (for building from git)
Perl 5.8.3 (for building from git)

PostgreSQL has many additional capabilities which can be enabled using
configure --enable switches but many of those also depend on additional
libraries.  See the installation instructions for details.

To build PostgreSQL, run the following commands:

./configure
make

PostgreSQL can then be installed using 'make install', which will
require being a superuser to install into the default directory.
The installation location can be changed by passing '--prefix' to
'configure'.  Run './configure --help' for additional options.


BUILDING ON WINDOWS
====================

Detailed instructions for building on Windows is available here:
https://www.postgresql.org/docs/current/static/install-windows.html

To build PostgreSQL on Windows, either Visual Studio Express 2017
for Windows Desktop or Microsoft Visual C++ 2005 (or later) should be
installed.  PostgreSQL can also be build using MinGW or Cygwin using
the Unix instructions.

... some details about how to actually use VSE 2017 would be good

CREATING YOUR FIRST DATABASE
============================

Once the PostgreSQL software is installed, the first step to having a
running database is to initialize a PostgreSQL database using the
'initdb' command, eg:

initdb -D mydatabase

After the database system has been initialized, PostgreSQL can be
started by using the pg_ctl command:

pg_ctl -D mydatabase -l logfile start

Once PostgreSQL is running, you can connect to it using the psql
command-line client.  A default database called 'postgres' was created
by 'initdb'.

BUILDING THE POSTGRESQL DOCUMENTATION
=====================================

Full documentation for PostgreSQL is available online here:
https://www.postgresql.org/docs/current/static/index.html

To build the PostgreSQL documentation on most Unix variants, the
following tools are required:

.... whatever these are

To build PostgreSQL's documentation on Unix, run:

./configure
make docs

The documentation, once built by 'make docs', will be available in
various formats in the 'doc/src/sgml' directory.

> >Now there is also a problem, the README would point out to the
> >development version of the documentation.  As this is made at working
> >using git, I could personally live with having stable branches also
> >refer to the development version, but it could also make sense to have
> >each stable branch point to the URL of the versions they work on.
>
> That is a bit problematic. The README lives on git first, and therefore
> should point to the development version. The release process
> can replace this with links to the current version.

I'm not sure that I'm really following this, because we aren't pointing
to the development documentation, just the 'current' documentation, and
that seems fine, and there's links on that page to the other versions of
the page for each major version of PostgreSQL, in case someone pulled an
older branch or such.

In short, I think we're fine to just use the 'current' URLs in this
README.

I'd also update the 'Makefile' bit we have at the root to refer to the
README instead of the INSTALL file.

Thanks!

Stephen

On 01.11.18 18:41, Stephen Frost wrote:
> Greetings,
>
> * Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
>> On 01.11.18 07:26, Michael Paquier wrote:
>>>> It includes links to the website, as well as the short version of the
>>>> installation instructions.
>>> +The installation instructions are listed on the website:
>>> +
>>> +https://www.postgresql.org/docs/current/static/install-short.html
> I don't think we should link to the "Short version" directly here, the
> above URL should be the "installation.html" one..  With a caveat, see
> below.

How about the attached one? Picked up your draft, and cleaned it up a bit.

-- 
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On Thu, Nov 01, 2018 at 01:41:33PM -0400, Stephen Frost wrote:
> I'm not sure that I'm really following this, because we aren't pointing
> to the development documentation, just the 'current' documentation, and
> that seems fine, and there's links on that page to the other versions of
> the page for each major version of PostgreSQL, in case someone pulled an
> older branch or such.

Imagine for example that Postgres switches from ./configure to cmake,
this makes the current version of the documentation invalid on
back-branches, still they refer to it.  If we target that stuff for
beginners, they may just look into those docs, without thinking that
they actually need the version of the docs with the branch checked out.

My 2c.
--
Michael

Greetings,

* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
> How about the attached one? Picked up your draft, and cleaned it up a bit.

(unsurprisingly) this is looking pretty good to me.

A few additional notes:

> PostgreSQL Database Management System
> =====================================
>
> This directory contains the source code distribution of the PostgreSQL
> database management system.
>
> PostgreSQL is an advanced object-relational database management system
> that supports an extended subset of the SQL standard, including
> transactions, foreign keys, subqueries, triggers, user-defined types
> and functions.  This distribution also contains C language bindings.
>
> PostgreSQL has many language interfaces, many of which are listed here:
>
>     https://www.postgresql.org/download

Honestly, I don't think the above link makes sense when we're saying
"here's where to go to download language interfaces."  We could maybe
link to https://www.postgresql.org/download/products/2-drivers-and-interfaces/
instead, but that link is really pretty messy, imv.

Instead, I'd just move the 'Download' section that's at the end up to
here.

> Building on Windows
> ===================
>
> Detailed instructions for building on Windows is available here:
> https://www.postgresql.org/docs/current/static/install-windows.html
>
> To build PostgreSQL on Windows, either Visual Studio Express 2017
> for Windows Desktop or Microsoft Visual C++ 2005 (or later) should be
> installed.  PostgreSQL can also be build using MinGW or Cygwin using
> the Unix instructions.

The above should say "can also be built", not "build".

> Initializing your Database
> ==========================
>
> Once the PostgreSQL software is installed, the first step to having a
> running database is to initialize a PostgreSQL database using the
> 'initdb' command, eg:
>
> initdb -D /path/to/mydatabase

We probably shouldn't say 'eg' but should use language similar to what
we say above, which would be "run this command" or so.

> Where '/path/to/mydatabase' is the directory where the database is
> going to be installed. This directory can exist, but must be empty.
> If it does not exist, 'initdb' will create it.
>
> After the database system has been initialized, PostgreSQL can be
> started by using the pg_ctl command:
>
> pg_ctl -D /path/to/mydatabase -l logfile start
>
> Once PostgreSQL is running, you can connect to it using the psql
> command-line client.  A default database called 'postgres' was created
> by 'initdb'.

I didn't include a full path intentionally, simply because paths look
different between Unix systems and Windows.  That said, I don't think
it's a big deal either way.

> Building the PostgreSQL Documentation
> =====================================

I've been going back and forth on this, but it seems like building the
documentation should maybe be above the Initializing a database..?  I
could go either way on it.

> Download
> ========
>
> The latest version of this software may be obtained at
> https://www.postgresql.org/download/.  For more information look at our
> web site located at https://www.postgresql.org/.

I'd suggest we change this to be something like:

The latest version of this software, both in source code form and as
binary packages for many platforms, may be obtained at
https://www.postgresql.org/download/.  For more information please visit
https://www.postgresql.org/.

Thanks!

Stephen

Greetings,

* Michael Paquier (michael@paquier.xyz) wrote:
> On Thu, Nov 01, 2018 at 01:41:33PM -0400, Stephen Frost wrote:
> > I'm not sure that I'm really following this, because we aren't pointing
> > to the development documentation, just the 'current' documentation, and
> > that seems fine, and there's links on that page to the other versions of
> > the page for each major version of PostgreSQL, in case someone pulled an
> > older branch or such.
>
> Imagine for example that Postgres switches from ./configure to cmake,
> this makes the current version of the documentation invalid on
> back-branches, still they refer to it.  If we target that stuff for
> beginners, they may just look into those docs, without thinking that
> they actually need the version of the docs with the branch checked out.

I'd say we're targeting beginner developers, not beginner computer
users.

That said, I suppose it wouldn't be all that hard to have a different
version of the README for each branch and to keep it updated as we make
releases.

One point I'll make though is that we do need to have the README checked
into git, since that's where most people are getting the source.

If we go down this route, the master branch should probably link to the
regularly built devel documentation, so that if/when we do make such a
change, we'll point people at the updated documentation too.

Thanks!

Stephen

On Thu, Nov 01, 2018 at 08:42:34PM -0400, Stephen Frost wrote:
> If we go down this route, the master branch should probably link to the
> regularly built devel documentation, so that if/when we do make such a
> change, we'll point people at the updated documentation too.

I don't know how others feel about such things, so I may be
overengineering a simple problem as well :)

Also, I have not looked in details at the perl tools used to change the
version number in the tree, but we'd likely want a solution which
updates automatically the README also in this case depending on the
version number, perhaps also making sure that for a git repository with
the master branch in use we don't want to point to the development
version of the docs.
--
Michael

Greetings,

* Michael Paquier (michael@paquier.xyz) wrote:
> On Thu, Nov 01, 2018 at 08:42:34PM -0400, Stephen Frost wrote:
> > If we go down this route, the master branch should probably link to the
> > regularly built devel documentation, so that if/when we do make such a
> > change, we'll point people at the updated documentation too.
>
> I don't know how others feel about such things, so I may be
> overengineering a simple problem as well :)
>
> Also, I have not looked in details at the perl tools used to change the
> version number in the tree, but we'd likely want a solution which
> updates automatically the README also in this case depending on the
> version number, perhaps also making sure that for a git repository with
> the master branch in use we don't want to point to the development
> version of the docs.

Updating version_stamp.pl should be pretty straight-forward to have it
also update the README for the back-branches and it shouldn't be hard to
teach it how to ignore the README on the master branch.

As for what's in the README on the master branch, I was saying that it
*should* point to the development documentation, since that should be
current with whatever is actually in the git repo (or only a day behind
or such).

Thanks!

Stephen

On 02.11.18 01:38, Stephen Frost wrote:
> Greetings,
>
> * Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
>> How about the attached one? Picked up your draft, and cleaned it up a bit.
> (unsurprisingly) this is looking pretty good to me.
>
> A few additional notes:

Incorporated. See the attached.

If that works for you, I will submit it to the Commitfest.


Regards,

-- 
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On Fri, Nov 02, 2018 at 06:47:19AM -0400, Stephen Frost wrote:
> As for what's in the README on the master branch, I was saying that it
> *should* point to the development documentation, since that should be
> current with whatever is actually in the git repo (or only a day behind
> or such).

Definitely!
--
Michael

Greetings,

* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
> On 02.11.18 01:38, Stephen Frost wrote:
> >* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
> >>How about the attached one? Picked up your draft, and cleaned it up a bit.
> >(unsurprisingly) this is looking pretty good to me.
> >
> >A few additional notes:
>
> Incorporated. See the attached.
>
> If that works for you, I will submit it to the Commitfest.

Yeah, looks pretty good to me, please register it in the CF system.

Thanks!

Stephen

On 03.11.18 18:06, Stephen Frost wrote:
> Greetings,
>
> * Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
>> On 02.11.18 01:38, Stephen Frost wrote:
>>> * Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
>>>> How about the attached one? Picked up your draft, and cleaned it up a bit.
>>> (unsurprisingly) this is looking pretty good to me.
>>>
>>> A few additional notes:
>> Incorporated. See the attached.
>>
>> If that works for you, I will submit it to the Commitfest.
> Yeah, looks pretty good to me, please register it in the CF system.

Done. Added you for review.

-- 
                Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On 03/11/2018 00:14, Andreas 'ads' Scherbaum wrote:
> GNU make, version 3.8 or newer
> ISO/ANSI C compilar (at least C99-compliant)
> Flex 2.5.31 or later, and Bison 1.875 or later (for building from git)
> Perl 5.8.3 (for building from git)

I'm not in favor of listing all these versions here.  It's one more
thing to keep updated.  The version requirements are not outrageous, so
we can assume that someone with a reasonably up-to-date development
machine has appropriate versions.

I'm also not convinced that this list is actually complete.  From an
"empty" start you'd typically need at least zlib and readline on top of
those.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Mon, Jan 28, 2019 at 10:21:03PM +0100, Peter Eisentraut wrote:
> I'm not in favor of listing all these versions here.  It's one more
> thing to keep updated.  The version requirements are not outrageous, so
> we can assume that someone with a reasonably up-to-date development
> machine has appropriate versions.

+1.  I have just looked at the patch, and my take is that listing all
the ways to build Postgres directly in the README is just a
duplication of what we already have in the documentation.  So I would
just rip out all that and keep a simple link to the documentation.

> I'm also not convinced that this list is actually complete.  From an
> "empty" start you'd typically need at least zlib and readline on top of
> those.

Yep.

For now I have moved the patch to next CF, waiting on author.
--
Michael

Hi,

On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
> +1.  I have just looked at the patch, and my take is that listing all
> the ways to build Postgres directly in the README is just a
> duplication of what we already have in the documentation.  So I would
> just rip out all that and keep a simple link to the documentation.

Well, the documentation cannot be built without the dependencies, and
not everyone has convenient internet access.  I'm not sure what the
solution to that is, but somehow consolidating that information in the,
by now pretty standardized, location of INSTALL seems pretty reasonable
to me.

Greetings,

Andres Freund

On 14/02/2019 20:13, Andres Freund wrote:
> On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
>> +1.  I have just looked at the patch, and my take is that listing all
>> the ways to build Postgres directly in the README is just a
>> duplication of what we already have in the documentation.  So I would
>> just rip out all that and keep a simple link to the documentation.
> 
> Well, the documentation cannot be built without the dependencies, and
> not everyone has convenient internet access.  I'm not sure what the
> solution to that is, but somehow consolidating that information in the,
> by now pretty standardized, location of INSTALL seems pretty reasonable
> to me.

(I suppose you meant README here.  The information is already in INSTALL.)

But the proposed additions don't actually mention the required
dependencies to build the documentation, so it wouldn't even achieve
that goal.

And if you don't have internet access, how did you get the git checkout?

The use case here seems pretty narrow.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Hi Andreas,

On 2/15/19 11:59 AM, Peter Eisentraut wrote:
> On 14/02/2019 20:13, Andres Freund wrote:
>> On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
>>> +1.  I have just looked at the patch, and my take is that listing all
>>> the ways to build Postgres directly in the README is just a
>>> duplication of what we already have in the documentation.  So I would
>>> just rip out all that and keep a simple link to the documentation.
>>
>> Well, the documentation cannot be built without the dependencies, and
>> not everyone has convenient internet access.  I'm not sure what the
>> solution to that is, but somehow consolidating that information in the,
>> by now pretty standardized, location of INSTALL seems pretty reasonable
>> to me.
> 
> (I suppose you meant README here.  The information is already in INSTALL.)
> 
> But the proposed additions don't actually mention the required
> dependencies to build the documentation, so it wouldn't even achieve
> that goal.
> 
> And if you don't have internet access, how did you get the git checkout?
> 
> The use case here seems pretty narrow.

Any thoughts on Peter and Andres' comments?

Regards,
-- 
-David
david@pgmasters.net

Hi,

On 2019-03-21 22:06:36 +0400, David Steele wrote:
> On 2/15/19 11:59 AM, Peter Eisentraut wrote:
> > On 14/02/2019 20:13, Andres Freund wrote:
> > > On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
> > > > +1.  I have just looked at the patch, and my take is that listing all
> > > > the ways to build Postgres directly in the README is just a
> > > > duplication of what we already have in the documentation.  So I would
> > > > just rip out all that and keep a simple link to the documentation.
> > > 
> > > Well, the documentation cannot be built without the dependencies, and
> > > not everyone has convenient internet access.  I'm not sure what the
> > > solution to that is, but somehow consolidating that information in the,
> > > by now pretty standardized, location of INSTALL seems pretty reasonable
> > > to me.
> > 
> > (I suppose you meant README here.  The information is already in INSTALL.)
> > 
> > But the proposed additions don't actually mention the required
> > dependencies to build the documentation, so it wouldn't even achieve
> > that goal.
> > 
> > And if you don't have internet access, how did you get the git checkout?
> > 
> > The use case here seems pretty narrow.
> 
> Any thoughts on Peter and Andres' comments?

Given nothing happened since then I think we ought to mark this as
returned with feedback? Will do so tomorrow.

Greetings,

Andres Freund

On 4/6/19 3:18 AM, Andres Freund wrote:
> 
> Given nothing happened since then I think we ought to mark this as
> returned with feedback? Will do so tomorrow.

Agreed, marked as Returned with Feedback.

Regards,
-- 
-David
david@pgmasters.net