On Tue, Mar 18, 2014 at 2:02 AM, Johannes Meixner <jsm...@suse.de> wrote: > On Mar 14 21:44 Jim Meyering wrote (excerpt): >> >> On Fri, Mar 14, 2014 at 9:32 PM, Bruce Dubbs <bruce.du...@gmail.com> >> wrote: >>>> >>>> See the guidelines in coreutils' HACKING file. > > ... > >>> Interesting. Looking at the coreutils-8.22 tarball, there is no HACKING >>> file. It's not in the coreutils-8.17 tarball either. It is in the git >>> tree >>> though. >> >> >> FYI, that is deliberate. >> You can get it here, too: >> >> http://git.savannah.gnu.org/cgit/coreutils.git/tree/HACKING >> >> If you're hacking on coreutils (as with most pkgs), you should be doing >> so via a git clone, with the very latest, not starting from a tarball, >> which is almost always out of date by at least a few commits. > > I agree for real upstream developers (i.e. who work as authors). > > But for casual external contributors it could be different: > > In particular experienced users that have it installed as binary > software package from a (Linux) distributor (e.g. as RPM package). > > Those users may find an issue and then install the matching source > package (e.g. a source RPM) so that they get the matching tarball > of their currently installed binary software, then change > that sources and provide a bugreport with patch to upstream. > > I think it won't hurt when even the binary software package contains > such files as documentation. If for example coreutils' HACKING file > would be installed as documentation, at least some experienced users > may find and read it and contribute to upstream accordingly.
This might help. I've Cc'd the coreutils discussion list. > In general I think the installed documentation should be complete. > > For example the coreutils README file could provide more specific > information how to contribute correctly to upstream. > > My currently installed coreutils-8.22 README file > (from an openSUSE coreutils-8.22 RPM package) contains > ------------------------------------------------------------------------ > If you obtained this file as part of a "git clone", then see the > README-hacking file. If this file came to you as part of a tar archive, > then see the file INSTALL for compilation and installation instructions. > ... > Send bug reports, questions, comments, etc. to bug-coreut...@gnu.org. > If you would like to suggest a patch, see the files README-hacking > and HACKING for tips. > ------------------------------------------------------------------------ > but I neither have README-hacking nor INSTALL nor HACKING installed. Those things are typically useful to tarball(INSTALL) or cloned-sources consumers, but as mentioned, at least README-hacking and HACKING may help a few new contributors get started. > Therefore the installed coreutils documentation looks incomplete from > my point of view regardless that it is probably considered correct > from upstream's point of view. > > Perhaps this is a packaging issue because the openSUSE coreutils RPM > coreutils.spec file basically contains > ------------------------------------------------------------------------ > %install > ... > make install DESTDIR="%buildroot" pkglibexecdir=%{_libdir}/%{name} > . > . > . > %files > ... > %doc COPYING NEWS README THANKS > ------------------------------------------------------------------------ > see > https://build.opensuse.org/package/view_file/Base:System/coreutils/coreutils.spec?expand=1 > > According to the INSTALL file in my coreutils-8.22 tarball > a plain "make install" should do "the right thing": > ------------------------------------------------------------------------ > 4. Type `make install' to install the programs and any data files and > documentation. > ------------------------------------------------------------------------ > > As far as I see it seems by default there is no documentation installed > (except man pages) which means that each coreutils distributor installs > a different set of documentation files. Installed by "make install"? That installs the build doc/*.info files, too. Those constitute the primary documentation. > I assume this is intended but I do not understand the reason behind. > > By the way: > I wonder why is there no INSTALL file in the coreutils > git source repository at git://git.sv.gnu.org/coreutils It is imported from the gnulib submodule when you run ./bootstrap, as you must when building from cloned sources. > I assume all this is intended and there are good reasons for it > but from my point of view it looks somehow strange. > > Kind Regards > Johannes Meixner Thanks for the feedback.