CONTRIBUTING.md

   1 Contributing to GNU Stow
   2 ========================
   3
   4 Development of Stow, and GNU in general, is a volunteer effort, and
   5 you can contribute.  If you'd like to get involved, it's a good idea to join
   6 the [stow-devel](https://lists.gnu.org/mailman/listinfo/stow-devel)
   7 mailing list.
   8
   9 Bug reporting
  10 -------------
  11
  12 Please follow the procedure described in [the "Reporting Bugs"
  13 section](https://www.gnu.org/software/stow/manual/html_node/Reporting-Bugs.html#Reporting-Bugs)
  14 of [the manual](README.md#documentation).
  15
  16 Development
  17 -----------
  18
  19 For [development sources](https://savannah.gnu.org/git/?group=stow)
  20 and other information, please see the [Stow project
  21 page](http://savannah.gnu.org/projects/stow/) at
  22 [savannah.gnu.org](http://savannah.gnu.org).
  23
  24 There is also a
  25 [stow-devel](https://lists.gnu.org/mailman/listinfo/stow-devel)
  26 mailing list (see [Mailing lists](README.md#mailing-lists)).
  27
  28 Please be aware that all program source files (excluding the test
  29 suite) end in `.in`, and are pre-processed by `Makefile` into
  30 corresponding files with that prefix stripped before execution.  So if
  31 you want to test any modifications to the source, make sure that you
  32 change the `.in` files and then run `make` to regenerate the
  33 pre-processed versions before doing any testing.  To avoid forgetting
  34 (which can potentially waste a lot of time debugging the wrong code),
  35 you can automatically run `make` in an infinite loop every second via:
  36
  37     make watch
  38
  39 (You could even use fancier approaches like
  40 [`inotifywait(1)`](https://www.man7.org/linux/man-pages/man1/inotifywait.1.html)
  41 or [Guard](https://guardgem.org/).  But those are probably overkill in
  42 this case where the simple `while` loop is plenty good enough.)
  43
  44 Testing
  45 ~~~~~~~
  46
  47 The test suite can be found in the [`t/`](t/) subdirectory.  You can
  48 run the test suite via:
  49
  50     make check
  51
  52 Tests can be run individually as follows.  First you have to ensure
  53 that the `t/`, `bin/`, and `lib/` directories are on Perl's search path.
  54 Assuming that you run all tests from the root of the repository tree,
  55 this will do the job:
  56
  57     export PERL5LIB=t:bin:lib
  58
  59 (Not all tests require all of these, but it's safer to include all of
  60 them.)
  61
  62 Secondly, be aware that if you want to test modifications to the
  63 source files, you will need to run `make watch`, or `make` before each
  64 test run as explained above.
  65
  66 Now running an individual test is as simple as:
  67
  68     perl t/chkstow.t
  69
  70 or with a given debugging verbosity corresponding to the `-v` / `--verbose`
  71 command-line option:
  72
  73     TEST_VERBOSE=4 perl t/chkstow.t
  74
  75 The [`prove(1)` test runner](https://perldoc.perl.org/prove) is another
  76 good alternative which provides several handy extra features.  Invocation
  77 is very similar, e.g.:
  78
  79     prove t/stow.t
  80
  81 or to run the whole suite:
  82
  83     prove
  84
  85 However currently there is an issue where this interferes with
  86 `TEST_VERBOSE`.
  87
  88 If you want to create test files for experimentation, it is
  89 recommended to put them in a subdirectory called `playground/` since
  90 this will be automatically ignored by git and the build process,
  91 avoiding any undesirable complications.
  92
  93 Test coverage
  94 ~~~~~~~~~~~~~
  95
  96 To view test coverage reports, first ensure that
  97 [`Devel::Cover`](https://metacpan.org/dist/Devel-Cover) is installed.
  98 Then type `make coverage`.  The last lines of the output should
  99 include something like:
 100
 101     HTML output written to /home/user/path/to/stow/cover_db/coverage.html
 102
 103 which you can open in a web browser to view the report.
 104
 105 Translating Stow
 106 ----------------
 107
 108 Stow is not currently multi-lingual, but patches would be very
 109 gratefully accepted. Please e-mail
 110 [stow-devel](https://lists.gnu.org/mailman/listinfo/stow-devel) if you
 111 intend to work on this.
 112
 113 Maintainers
 114 -----------
 115
 116 Stow is currently being maintained by Adam Spiers.  Please use [the
 117 mailing lists](README.md#mailing-lists).
 118
 119 Helping the GNU project
 120 -----------------------
 121
 122 For more general information, please read [How to help
 123 GNU](https://www.gnu.org/help/).