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