Thread: INSTALL file
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:
- Update the README, and remove the "INSTALL" reference
- Create a permanent INSTALL file, and possibly overwrite it during packaging
- Add different INSTALL files, based on the platform (Linux, BSD, Windows, Source)
Regards,
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
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
Attachment
> 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.
If you push a README.md file formatted in Markdown, github/gitlab will show it instead of README.
That's the way it is done in PostGIS, showing badges and stuff for github only:
Darafei Praliaskouski
Support me: http://patreon.com/komzpa
Support me: http://patreon.com/komzpa
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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
Attachment
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