README-hacking 9.1 KB

  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. If you want to submit a patch, please start from checked-out sources
  4. rather than the source tarball.
  5. Prerequisites
  6. =============
  7. * git (to check out both findutils and gnulib).
  8. * A C compiler, linker and software development libraries (the standard
  9. C library). Any compiler compliant with the 1990 ISO C standard running
  10. on a POSIX system should work.
  11. * GNU Autoconf
  12. * GNU Automake
  13. * GNU m4
  14. * GNU gettext
  15. * GNU Dejagnu
  16. Dejagnu is in fact optional, but it's strongly recommended, since it is
  17. needed to run findutils' test suite (which is how you know that find
  18. works once it is built on your system).
  19. The configure program should tell you if you try to use a version of
  20. one of these tools which is not of a recent enough version. The file
  21. tool-versions.txt indicates which version of each tool the current
  22. release was built and tested with. This is included in the tar-file
  23. releases, but it's not checked in to git.
  24. Use the latest upstream sources
  25. ===============================
  26. 1. Check out the findutils code
  27. git clone git://
  28. This will download the whole repository, it's about 16MB once fetched.
  29. If you already have a copy you can refresh it with:
  30. git checkout master (to switch to your copy of the master branch)
  31. git pull (to collect and merge changes)
  32. 2. Generate a gnulib installation within the findutils source tree
  33. Change your working directory to the findutils source directory (that
  34. is, the directory containing this file). Then run the following
  35. command:-
  36. ./bootstrap
  37. This command will use git to check out the version of gnulib which is
  38. intended to work with the findutils source you already have (gnulib
  39. is used as a git submodule). The gnulib code itself is left in the
  40. directory "gnulib". The "gl" directory contains just the gnulib
  41. files that findutils needs during the build process.
  42. This will also run Autoconf and Automake to generate the "configure"
  43. script and "" files.
  44. 3. Run "./configure" and "make" in the normal way.
  45. If you have GNU libintl installed, you can just run "./configure".
  46. Otherwise, run "./configure --disable-nls".
  47. You are now at the point where your local directory looks just like it
  48. would after building a source release, except that your copy is more
  49. up-to-date.
  50. *Before* you commit changes
  51. ===========================
  52. In this project, we much prefer patches that automatically record
  53. authorship. That is important not just to give credit where due, but
  54. also from a legal standpoint (see below). To create author-annotated
  55. patches with git, you must first tell git who you are. That information
  56. is best recorded in your ~/.gitconfig file. Edit that file, creating
  57. it if needed, and put your name and email address in place of these
  58. example values:
  59. [user]
  60. name = Joe X. User
  61. email =
  62. Required format for check-in messages
  63. =====================================
  64. We use a specific style for check-in messages. See "git log" for
  65. examples. The format corresponds to the standard GNU ChangeLog
  66. format, but without date & author headers (since git provides this
  67. data) and without a left margin (since there are no headers).
  68. --- example begins ---
  69. Don't overflow sig_atomic_t for --max-procs.
  70. * xargs/xargs.c (__STDC_LIMIT_MACROS): Define __STDC_LIMIT_MACROS
  71. in order to ensure that <stdint.h> defines the SIG_ATOMIC_MAX
  72. macro, which we need.
  73. (MAX_PROC_MAX): Define this as the maximum allowed value of
  74. proc_max.
  75. (main): Show the value of MAX_PROC_MAX for --show-limits.
  76. (increment_proc_max): Don't increment proc_max beyond
  78. --- example ends ---
  79. There are several things to notice about this checkin message. Most
  80. importantly, it begins with a single line summary of the whole change.
  81. This needs to be short. It would be used as the subject line of
  82. patches mailed by "git send-email". Some people begin that line with
  83. a one-word tag indicating what is affected (for example find: for
  84. changes to find, doc: to changes to the documentation, maint: for
  85. changes to the maintainer automation and so forth).
  86. All changes to a file are grouped together in an entry which begins with
  87. an asterisk (*) and the file name. The name of the modified function
  88. (if any) follows immediately in parentheses followed by a colon. If
  89. you're modifying a file for which "function" isn't the logical unit of
  90. organisation, use whatever seems most useful. For example when
  91. modifying the Texinfo source, use the section name.
  92. After the colon, describe the change you made to that function. If
  93. you made a related change mention the places you made that change,
  94. too. If you made many individually small changes, you can summarise
  95. these if they're not individually interesting. For example you could
  96. just say "Update all callers to remove this function argument". If
  97. that change spans several files, mention the other files modified.
  98. Note for maintainers:
  99. Prior to pushing a commit in the name of someone else to the public
  100. Git repository, please check if that person has undergone the
  101. "Copyright assignment" process for GNU findutils described below, or -
  102. in case of a trivial change (<10 lines, cumulatively with all their
  103. previous contributions) - document that such paperwork is not required
  104. by adding this line to the commit message:
  105. Copyright-paperwork-exempt: Yes
  106. Making commits locally
  107. ======================
  108. You will normally find it much easier to work on a branch. This
  109. allows you to maintain your changes and test them without being
  110. affected by changes on the trunk.
  111. To Make a "topic" branch for your change, do this:
  112. git branch my-topic
  113. git checkout my-topic
  114. You can then work on your branch as normal.
  115. To update your local repository, do this:
  116. git checkout master
  117. git pull
  118. Then, rebase your topic branch to take into account the upstream
  119. changes you just pulled:
  120. git checkout my-topic
  121. git rebase master
  122. There are some useful checks that git commit hooks will do for you,
  123. it's a good idea to enable these:
  124. mv .git/hooks/pre-commit.sample .git/hooks/pre-commit
  125. Submitting patches
  126. ==================
  127. If you plan to submit changes to findutils, please make sure you have
  128. read the GNU coding standard (
  129. Some common things you might have forgotten to do are:
  130. - document your change in both the manual pages and the Texinfo file
  131. - re-run the test suite (with Dejagnu installed!)
  132. - add a test case for the bug you're fixing or feature you're adding
  133. - mention your fix or change (if it's significant) in the NEWS file
  134. - commit using a descriptive commit message
  135. If you have patches, please generate them with "git format-patch" and
  136. mail them to these addresses:
  138. Here is a complete session
  139. # set up your topic branch
  140. git checkout master
  141. git pull
  142. git branch my-topic
  143. git checkout my-topic
  144. # update the code, documentation, test suite and change log, run tests
  145. emacs xargs/xargs.c
  146. emacs doc/find.texi xargs/xargs.1
  147. emacs xargs/testsuite/ xargs/testsuite/xargs.gnu/blah.exp
  148. make check
  149. emacs NEWS
  150. # make sure you didn't break anything
  151. make syntax-check
  152. make distcheck
  153. # commit the change and send the patches.
  154. git add -u
  155. git commit
  156. git rebase master
  157. mkdir /tmp/patches
  158. git format-patch -o /tmp/patches master..HEAD
  159. git send-email --compose \
  160. --to \
  161. --cc /tmp/patches
  162. Copyright assignment
  163. ====================
  164. If your change is significant (i.e., if it adds more than ~10 lines),
  165. then you'll have to have a copyright assignment on file with the FSF.
  166. Since that involves first an email exchange between you and the FSF,
  167. and then the exchange (FSF to you, then back) of an actual sheet of
  168. paper with your signature on it, and finally, some administrative
  169. processing in Boston, the process can take a few weeks (for
  170. contributors in some geographies, this can all be done electronically,
  171. saving a lot of time).
  172. The forms to choose from are in gnulib's doc/Copyright/ directory.
  173. If you want to assign a single change, you should use the file,
  174. doc/Copyright/request-assign.changes:
  176. If you would like to assign past and future contributions to a project,
  177. you'd use doc/Copyright/request-assign.future:
  179. You may make assignments for up to four projects at a time.
  180. In case you're wondering why we bother with all of this, read this:
  182. ========================================================================
  183. Copyright (C) 2009-2021 Free Software Foundation, Inc.
  184. Permission is granted to copy, distribute and/or modify this document
  185. under the terms of the GNU Free Documentation License, Version 1.3 or
  186. any later version published by the Free Software Foundation; with no
  187. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  188. A copy of the license is included in the ``GNU Free Documentation
  189. License'' file as part of this distribution.