This is the README file for the GNU Hello distribution.
Hello prints a friendly greeting.  It also serves as a sample GNU
package, showing practices that may be useful for GNU projects.

  Copyright (C) 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
  2002, 2004, 2005, 2006, 2010, 2013, 2014 Free Software Foundation,
  Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

See the files ./INSTALL* for building and installation instructions.

Primary distribution point: ftp://ftp.gnu.org/gnu/hello/
 automatic redirection: http://ftpmirror.gnu.org/hello
 list of mirrors for manual selection: http://www.gnu.org/prep/ftp.html

Home page: http://www.gnu.org/software/hello/

Developer page: http://savannah.gnu.org/projects/hello/
- please file bug reports, patches and feature requests here if
  possible (otherwise, feel free to use the mailing list)
- significant contributions require a copyright assignment to the Free
  Software Foundation. The maintainer will be happy to answer
  questions about the process.

Mailing list: bug-hello@gnu.org
- please use this list for all discussion
- archived at: http://lists.gnu.org/pipermail/bug-hello
- anyone is welcome to join the list; to do so, visit
  http://lists.gnu.org/mailman/listinfo/bug-hello

Bug reports:
 Please include enough information for the maintainers to reproduce the
 problem.  Generally speaking, that means:
- the contents of any input files necessary to reproduce the bug
  and command line invocations of the program(s) involved (crucial!).
- a description of the problem and any samples of the erroneous output.
- the version number of the program(s) involved (use --version).
- hardware, operating system, and compiler versions (uname -a).
- unusual options you gave to configure, if any (see config.status).
- anything else that you think would be helpful.

Patching process:
- All changes must be sent to mailing list.
- Changes are reviewed by maintainers.
- Maintainer does not review own changes.
  * In case of single maintainer, or unresponsive co-maintainer, mailing
    list subscribers may perform the review.
- Review means either a patch approval, comments to author, or a reject.
  * Approved patches are taken to upstream git.
  * Commented patches will require work before they can be approved.
    Comments can be untechnical, such as a change author must submit a
    copyright assignment to FSF.
  * Authors are encouraged to discontinue work with rejected changes, as
    the reject is permanent.
- Maintainers keep track of rejected changes so that developers can avoid
  proposing the same in future.

Patches are most welcome; if possible, please make them in git-am
format, and include a suitable commit message.

See README-dev for information on the development environment -- any
interested parties are welcome.  If you're a programmer and wish to
contribute, this should get you started.  If you're not a programmer,
your help in writing test cases, checking the documentation against the
implementation, translating the program strings to other languages,
etc., would still be very much appreciated.

The basic Hello algorithm was described by B.W. Kernighan and
D.M. Ritchie.  The GNU implementation is substantially more complex, in
order to be a canonical example of a GNU package.  Many people have
contributed; please see the AUTHORS and ChangeLog files.

GNU Hello is free software.  See the file COPYING for copying conditions.

This README.dev file describes the development environment.

  Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
  2011, 2012, 2014 Free Software Foundation, Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

The development sources are available through git  at Savannah:

  https://savannah.gnu.org/git/?group=hello


Autotools
---------

This distribution uses whatever versions of Automake, Autoconf and
Gettext are listed in NEWS; usually the latest ones released.  If you
are getting the sources from git (or change configure.ac), you'll
need to have these tools installed to (re)build.  You'll also need
help2man.  All of these programs are available from
ftp://ftp.gnu.org/gnu.


Building
--------

After getting the git sources, and installing the tools above, you
can run

  ./bootstrap

to do a fresh build.  After that first time, running make should suffice.

When modifying the sources, or making a distribution, more is needed, as
follows:


Gnulib
------

This distribution also uses Gnulib (http://www.gnu.org/software/gnulib)
to share common files, stored as a submodule in git.


Gettext
-------

When updating gettext, besides the normal installation on the system, it
is necessary to run gettextize -f in this hierarchy to update the po/
infrastructure.  After doing so, rerun gnulib-tool --import since
otherwise older files will have been imported.  See the Gnulib manual
for more information.

Here are most of the steps we (maintainers) follow when making a release.

* Start from a clean, up-to-date git directory on "master":

    make -k maintainer-clean || { ./configure && make maintainer-clean; }
    git checkout master
    git pull origin master

* Ensure that the latest stable versions of autoconf, automake, etc.
  are in your PATH.  See the buildreq list in bootstrap.conf for
  the complete list of tools.

* Ensure that you have no uncommitted diffs.  This should produce no
  output:

    git diff

* Ensure that you've pushed all changes that belong in the release:

    git push origin master

* Check that the NixOS/Hydra autobuilder is reporting all is well:

    http://hydra.nixos.org/jobset/gnu/@PACKAGE@-master

* Run the following command to download any new translations:

    ./bootstrap && ./configure

* Pre-release testing: ensure that the following command succeeds:

    make check syntax-check distcheck

* To (i) set the date, version number, and release TYPE on line 3 of
  NEWS, (ii) commit that, and (iii) tag the release, run

    # "TYPE" must be stable, beta or alpha
    make release-commit RELEASE='X.Y TYPE'

* Run the following to create release tarballs.  Your choice selects the
  corresponding upload-to destination in the emitted gnupload command.
  The different destinations are specified in cfg.mk.  See the definitions
  of gnu_ftp_host-{alpha,beta,stable}.

    make release RELEASE='X.Y TYPE'

* Test the tarball.  Copy it to a few odd-ball systems and ensure that
  it builds and passes all tests.

* While that's happening, write the release announcement that you will
  soon post.  Start with the template, $HOME/announce-@PACKAGE@-X.Y
  that was just created by that "make" command.

Once all the builds and tests have passed,

* Run the gnupload command that was suggested by your "make release"
  run above, or run

    make upload RELEASE='X.Y TYPE'

* Wait a few minutes (maybe up to 30?) and then use the release URLs to
  download all tarball/signature pairs and use gpg --verify to ensure
  that they're all valid.

* Push the NEWS-updating changes and the new tag:

    v=$(cat .prev-version)
    git push origin master tag v$v

* Announce it on Savannah first, so you can include the savannah.org
  announcement link in the email message.

  Go to the news-submission form:

    https://savannah.gnu.org/news/submit.php?group=@PACKAGE@

  If it does not work, then enable "News" for the project via this link:

    https://savannah.gnu.org/project/admin/editgroupfeatures.php?group=@PACKAGE@

  Write something like the following:

    Subject: @PACKAGE@-X.Y released [stable]
    +verbatim+
    ...paste the announcement here...
    -verbatim-

  Then go here to approve it:

    https://savannah.gnu.org/news/approve.php?group=@PACKAGE@

* Send the announcement email message.

* After each non-alpha release, run

    make web-manual-update

  to update the on-line manual accessible at

    http://www.gnu.org/software/@PACKAGE@/manual/