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