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.
4 If you want to submit a patch, please start from checked-out sources
5 rather than the source tarball.
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.
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).
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.
32 Use the latest upstream sources
33 ===============================
35 1. Check out the findutils code
37 git clone git://git.sv.gnu.org/findutils
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:
42 git checkout master (to switch to your copy of the master branch)
43 git pull (to collect and merge changes)
45 2. Generate a gnulib installation within the findutils source tree
47 Change your working directory to the findutils source directory (that
48 is, the directory containing this file). Then run the following
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.
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 :-
63 aclocal -I m4 -I gnulib/m4 && \
66 automake --add-missing --copy
68 3. Run "configure" and "make" in the normal way.
70 If you have GNU libintl installed, you can just run "configure".
71 Otherwise, run "configure --disable-nls".
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
77 *Before* you commit changes
78 ===========================
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
90 email = joe.user@example.com
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.
102 Making commits locally
103 ======================
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.
109 To Make a "topic" branch for your change, do this:
112 git checkout my-topic
114 You can then work on your branch as normal.
116 To update your local repository, do this:
121 Then, rebase your topic branch to take into account the upstream
122 changes you just pulled:
124 git checkout my-topic
127 There are some useful checks that git commit hooks will do for you,
128 it's a good idea to enable these:
130 chmod +x .git/hooks/pre-commit
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:
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
146 If you have patches, please generate them with "git format-patch" and
147 mail them to these addresses:
149 bug-findutils@gnu.org, findutils-patches@gnu.org
151 Here is a complete session
153 # set up your topic branch
157 git checkout my-topic
159 # update the code, documentation, test suite and change log, run tests
161 emacs doc/find.texi xargs/xargs.1
162 emacs xargs/testsuite/Makefile.am xargs/testsuite/xargs.gnu/blah.exp
166 # make sure you didn't break anything
169 # commit the change and send the 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
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).
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:
196 http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.changes;hb=HEAD
198 If you would like to assign past and future contributions to a project,
199 you'd use doc/Copyright/request-assign.future:
201 http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.future;hb=HEAD
203 You may make assignments for up to four projects at a time.
205 In case you're wondering why we bother with all of this, read this:
207 http://www.gnu.org/licenses/why-assign.html
210 ========================================================================
211 Copyright (C) 2009, 2010, 2014 Free Software Foundation, Inc.
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.