diff options
author | G. Branden Robinson <g.branden.robinson@gmail.com> | 2022-05-24 11:25:09 -0500 |
---|---|---|
committer | G. Branden Robinson <g.branden.robinson@gmail.com> | 2022-05-24 11:25:09 -0500 |
commit | bd43408faa9617d61415e9fcf63d29894e355268 (patch) | |
tree | e5e70e8c06d80b7bdde1ec52fb07212872373699 /HACKING | |
parent | 1babd919ab6479e844669b012a2acf73cc6ef3d9 (diff) | |
download | groff-git-bd43408faa9617d61415e9fcf63d29894e355268.tar.gz |
HACKING: Add developer-facing advice document.
This scoops up the 'automake.mom' material just dropped from
'INSTALL.REPO', and summarizes a couple of discussions from the mailing
list over the past 2 years or so.
Diffstat (limited to 'HACKING')
-rw-r--r-- | HACKING | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/HACKING b/HACKING new file mode 100644 index 000000000..ff7014d77 --- /dev/null +++ b/HACKING @@ -0,0 +1,70 @@ + Copyright 2022 Free Software Foundation, Inc. + + Copying and distribution of this file, with or without + modification, are permitted in any medium without royalty provided + the copyright notice and this notice are preserved. + +This file contains advice on developing and contributing to groff. It +assumes that developers will install the 'git' revision control +system and build groff using the instructions in 'INSTALL.repo'. + +Automake +-------- + +A document explaining the basics of GNU Automake and its usage in groff +is available in 'doc/automake.mom'; a PDF rendering is built but not +installed, since it is a developer-facing discussion. Peruse it in +'doc/automake.pdf' in your build tree. + + +Testing +------- + +Running the test suite with 'make check' after building any substantive +change to groff logic is encouraged. You should certainly do so, and +confirm that the tests pass, before submitting patches to the groff +mailing list <groff@gnu.org> or Savannah issue tracker. + +If you find a defect in a test script, that can be reported via Savannah +like any other bug. + + +Documenting changes +------------------- + +The groff project has a long history and a large, varied audience. +Changes may need to be documented in up to three places depending on +their impact. + +1. Changes should of course be documented in the Git commit message. + If a change does not resolve a Savannah ticket, alters only + comments to source code, or makes editorial changes to + documentation, you can stop at that. + +2. The 'ChangeLog' file follows the format and practices documented in + the GNU Coding Standards. + https://www.gnu.org/prep/standards/html_node/Change-Logs.html + + The sub-projects in the 'contrib' directory each have their own + dedicated ChangeLog files. The file specifications documented there + are relative to the sub-project, not the root of the groff source + tree. When converted to a commit message, add 'contrib/$SUBPROJECT' + to the entries. + + Apart from 'contrib', groff uses a single (current) 'ChangeLog' file + for the rest of its source tree. + + It is convenient to write the ChangeLog entry or entries first, then + construct a commit message from it (or them). + +3. The 'NEWS' file documents changes to groff that a user, not just a + developer, would notice, not including the resolution of defects. + + As a hypothetical example, correcting a rendering error in tbl(1) + such that any table with more than 20 rows no longer had the text + "FOOBAR" added to some of entries would not be a 'NEWS' item, + because the appearance of such text in the first place is a + surprising deviation from tbl's ideal and historical behavior. In + contrast, adding a command-line option to tbl, or changing the + meaning of its "expand" region option such that it no longer + horizontally compresses tables as well, _would_ be 'NEWS'-worthy. |