README-hacking

   1 These notes intend to help people working on the checked-out sources.
   2 They don't apply when you are building from a distribution tarball.
   3
   4 If you want to submit a patch, please start from checked-out sources
   5 rather than the source tarball.
   6
   7
   8 Prerequisites
   9 =============
  10
  11  * git (to check out both findutils and gnulib).
  12  * A C compiler, linker and software development libraries (the standard
  13    C library).  Any compiler compliant with the 1990 ICO C standard running
  14    on a POSIX system should work.
  15  * GNU Autoconf
  16  * GNU Automake
  17  * GNU m4
  18  * GNU gettext
  19  * GNU Dejagnu
  20
  21 The configure program should tell you if you try to use a version of
  22 one of these tools which is not oif a recent enough version.  The file
  23 tool-versions.txt indicates which version of each tool the current
  24 release was built and tested with.
  25
  26
  27 Use the latest upstream sources
  28 ===============================
  29
  30 1. Check out the findutils code
  31
  32   git clone git://git.sv.gnu.org/findutils
  33
  34 This will download the whole repository, it's about 14MB.  If you
  35 already have a copy you can refresh it with
  36
  37   git checkout master  (to switch to your copy of the master branch)
  38   git pull (to collect and merge changes)
  39
  40 2. Generate a gnulib installation within the findutils source tree
  41
  42  Change your working directory to the findutils source directory (that
  43  is, the directory containing this file).   Then run the following
  44  command:-
  45
  46     sh import-gnulib.sh
  47
  48  This command will use git to check out the version of gnulib which is
  49  intended to work with the findutils source you already have, as
  50  configured by the file import-gnulib.config.  The gnulib code itself
  51  is left in the directory "gnulib-git".  The "gnulib" directory
  52  contains just the gnulib files that findutils needs during the build
  53  process.
  54
  55  If you want to build findutils with a different version of gnulib,
  56  just edit import-gnulib.config to change the version and then re-run
  57  import-gnulib.sh.  When specifying the version, you can specify
  58  either the date or a tag.  If making any kind of release, please
  59  use a fully identifying version (rather than just, say, "HEAD").
  60
  61  The import-gnulib.sh script will also run Autoconf and Automake to
  62  generate the "configure" script and "Makefile.in" files.  Should you
  63  need to do this manually, you can do it like this :-
  64
  65     aclocal -I m4 -I gnulib/m4     && \
  66     autoheader                     && \
  67     autoconf                       && \
  68     automake --add-missing --copy
  69
  70 3. (Optional) Update the translations
  71
  72     rsync -Lrtvz  translationproject.org::tp/latest/findutils/ po
  73
  74 3. Run "configure" and "make" in the normal way.
  75
  76  If you have GNU libintl installed, you can just run "configure".
  77  Otherwise, run "configure --disable-nls".
  78
  79 You are now at the point where your local directory looks just like it
  80 would after building a source release, except that your copy is more
  81 up-to-date.
  82
  83 *Before* you commit changes
  84 ===========================
  85
  86 In this project, we much prefer patches that automatically record
  87 authorship.  That is important not just to give credit where due, but
  88 also from a legal standpoint (see below).  To create author-annotated
  89 patches with git, you must first tell git who you are.  That information
  90 is best recorded in your ~/.gitconfig file.  Edit that file, creating
  91 it if needed, and put your name and email address in place of these
  92 example values:
  93
  94 [user]
  95   name = Joe X. User
  96   email = joe.user@example.com
  97
  98
  99 In order to simplify the handling of merges, we recommend that you
 100 use a specialised merge driver for the ChangeLog file.  Otherwise,
 101 you will end up spending time resolving merge conflicts for your
 102 ChangeLog edits.  You can install the ChangeLog merge driver by
 103 following the instructions in the README section of the file
 104 gnulib-git/gnulib/lib/git-merge-changelog.c.
 105
 106
 107
 108 Making commits locally
 109 ======================
 110
 111 You will normally find it much easier to work on a branch.  This
 112 allows you to maintain your changes and test them without being
 113 affected by changes on the trunk.
 114
 115 To Make a "topic" branch for your change, do this:
 116
 117   git branch my-topic
 118   git checkout my-topic
 119
 120 You can then work on your branch as normal.
 121
 122 To update your local repository, do this:
 123
 124   git checkout master
 125   git pull
 126
 127 Then, rebase your topic branch to take into account the upstream
 128 changes you just pulled:
 129
 130   git checkout my-topic
 131   git rebase master
 132
 133 There are some useful checks that git commit hooks will do for you,
 134 it's a good idea to enable these:
 135
 136   chmod +x .git/hooks/pre-commit
 137
 138
 139 Submitting patches
 140 ==================
 141
 142 If you plan to submit changes to findutils, please make sure you have
 143 read the GNU coding standard (http://www.gnu.org/prep/standards/).
 144 Some common things you might have forgotten to do are:
 145
 146  - document your change in both the manual pages and the Texinfo file
 147  - re-run the test suite (with Dejagnu installed!)
 148  - add a ChangeLog entry (for now we still do that manually)
 149  - add a test case for the bug you're fixing or feature you're adding
 150  - mention your fix or change (if it's significant) in the NEWS file
 151
 152 If you have patches, please generate them with "git format-patch" and
 153 mail them to these addresses:
 154
 155   bug-findutils@gnu.org, findutils-patches@gnu.org
 156
 157 Here is a complete session
 158
 159   # set up your topic branch
 160   git checkout master
 161   git pull
 162   git branch my-topic
 163   git checkout my-topic
 164
 165   # update the code, documentation, test suite and change log, run tests
 166   emacs xargs/xargs.c
 167   emacs doc/find.texi xargs/xargs.1
 168   emacs xargs/testsuite/Makefile.am  xargs/testsuite/xargs.gnu/blah.exp
 169   make check
 170   emacs ChangeLog NEWS
 171
 172   # make sure you didn't break anything
 173   make distcheck
 174
 175   # commit the change and send the patches.
 176   git add -u
 177   git commit
 178   git rebase master
 179   mkdir /tmp/patches
 180   git format-patch -o /tmp/patches master..HEAD
 181   git send-email --compose \
 182       --to bug-findutils@gnu.org \
 183       --cc findutils-patches@gnu.org /tmp/patches
 184
 185
 186 Copyright assignment
 187 ====================
 188
 189 If your change is significant (i.e., if it adds more than ~10 lines),
 190 then you'll have to have a copyright assignment on file with the FSF.
 191 Since that involves first an email exchange between you and the FSF,
 192 and then the exchange (FSF to you, then back) of an actual sheet of paper
 193 with your signature on it, and finally, some administrative processing
 194 in Boston, the process can take a few weeks.
 195
 196 The forms to choose from are in gnulib's doc/Copyright/ directory.
 197 If you want to assign a single change, you should use the file,
 198 doc/Copyright/request-assign.changes:
 199
 200     http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.changes;hb=HEAD
 201
 202 If you would like to assign past and future contributions to a project,
 203 you'd use doc/Copyright/request-assign.future:
 204
 205     http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.future;hb=HEAD
 206
 207 You may make assignments for up to four projects at a time.
 208
 209 In case you're wondering why we bother with all of this, read this:
 210
 211     http://www.gnu.org/licenses/why-assign.html
 212
 213
 214 ========================================================================
 215 Copyright (C) 2009, 2010 Free Software Foundation, Inc.
 216
 217 Permission is granted to copy, distribute and/or modify this document
 218 under the terms of the GNU Free Documentation License, Version 1.3 or
 219 any later version published by the Free Software Foundation; with no
 220 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 221 Texts.  A copy of the license is included in the ``GNU Free
 222 Documentation License'' file as part of this distribution.