Debian Codegraph @

doc/source/CONTRIBUTING.rst

raw
1 .. _CONTRIBUTING:
2
3 Contributing
4 ============
5
6 Thank you for considering contributing to Modules! Modules is an open source
7 project. Questions, discussion, and contributions are welcome.
8
9 By contributing to this project, you agree to follow our `Code of conduct`_,
10 which ensures a respectful and inclusive environment for all contributors.
11 Please review it before participating in discussions or submitting
12 contributions.
13
14 .. _Code of conduct: https://github.com/envmodules/modules?tab=coc-ov-file#readme
15
16 This project also adheres to a :ref:`Technical charter<CHARTER>`, which
17 defines its governance model, decision-making process, and long-term vision.
18
19 Support questions
20 -----------------
21
22 Please use the `modules-interest mailing list`_
23 (``[email protected]``) or the `Modules chat room`_
24 (``#modules:matrix.org``) for questions. Do not use the
25 issue tracker for this.
26
27 .. _modules-interest mailing list: https://lists.hpsf.io/g/modules-interest
28 .. _Modules chat room: https://matrix.to/#/#modules:matrix.org
29
30 Asking for new features
31 -----------------------
32
33 Please submit your new feature wishes first to the `modules-interest mailing
34 list`_ or `Modules chat room`_. Discussion will help to clarify your needs and
35 sometimes the wanted feature may already be available.
36
37 Reporting issues
38 ----------------
39
40 * Describe what you expected to happen.
41 * If possible, include a `minimal, complete, and verifiable example`_ to help
42 us identify the issue.
43 * Describe what actually happened. Run the ``module`` command in ``--debug``
44 mode and include all the debug output obtained in your report.
45 * Provide the current configuration and state of your Modules installation by
46 running the ``module config --dump-state`` command.
47 * Provide the name and content of the modulefiles you try to manipulate.
48
49 .. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve
50
51 If you find a security vulnerability, please refer to our `security policy`_
52 for guidelines on how to report such issues responsibly.
53
54 .. _security policy: https://github.com/envmodules/modules/security
55
56 .. _tsc-meeting:
57
58 TSC meeting
59 -----------
60
61 A meeting of the Technical Steering Committee (TSC) is organized every
62 quarter. This meeting is open to anyone willing to learn more about the
63 project and its ongoing activities.
64
65 The TSC usually defines or refines the roadmap for the next version during
66 this meeting. The community may also raise their concerns or questions to the
67 maintainers.
68
69 Please visit the `Modules wiki`_ to find the date and time of the next TSC
70 meeting, along with the connection details for joining the virtual session.
71 The wiki also includes the agenda for upcoming meetings and notes from
72 previous ones.
73
74 .. _Modules wiki: https://github.com/envmodules/modules/wiki
75
76 .. _submitting-patches:
77
78 Submitting patches
79 ------------------
80
81 * Whether your patch is supposed to solve a bug or add a new feature, please
82 include tests. In case of a bug, explain clearly under which circumstances
83 it happens and make sure the test fails without your patch.
84 * If you are not yet familiar with the ``git`` command and `GitHub`_, please
85 read the `don't be afraid to commit`_ tutorial.
86
87 .. _GitHub: https://github.com/
88 .. _don't be afraid to commit: https://afraid-to-commit.readthedocs.io/en/latest/index.html
89
90 Start coding
91 ~~~~~~~~~~~~
92
93 * Create a branch to identify the issue or feature you would like to work on
94 * Using your favorite editor, make your changes, `committing as you go`_
95 and following the `commit message conventions
96 <commit-message-conventions_>`_ of this project.
97 * Comply to the `coding conventions of this project <coding-conventions_>`_
98 and its `code comments guidelines <code-comments_>`_.
99 * Your Tcl code has to be compatible with Tcl version 8.5 and above (see
100 `Tcl 8.5 commands reference`_)
101 * Include tests that cover any code changes you make. Make sure the test fails
102 without your patch.
103 * `Run the tests <running-the-tests_>`_ and `verify coverage <running-test-coverage_>`_.
104 * `Sign-off your commits <developer-certificate-of-origin_>`_.
105 * If you used `AI coding assistants <ai-coding-assistants_>`_, disclose it in
106 your commit message.
107 * Push your commits to GitHub and `create a pull request`_.
108
109 .. _committing as you go: https://afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
110 .. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
111 .. _Tcl 8.5 commands reference: https://www.tcl-lang.org/man/tcl8.5/TclCmd/contents.htm
112
113 Developer notes
114 ~~~~~~~~~~~~~~~
115
116 See the :ref:`design` for recent feature specifications. Some development
117 howtos are also available:
118
119 * :ref:`add-new-sub-command`
120 * :ref:`add-new-config-option`
121 * :ref:`add-new-hook-event`
122 * :ref:`devel-testsuite`
123
124 .. _running-the-tests:
125
126 Running the tests
127 ~~~~~~~~~~~~~~~~~
128
129 Run the basic test suite with::
130
131 make test
132
133 This only runs the tests for the current environment. `GitHub Actions`_ will
134 run the full suite when you submit your pull request. See
135 :ref:`devel-testsuite` for a full description of how the testsuite is
136 organized and how to add or debug tests.
137
138 There are around 25 000 test cases thus it generally takes around 12
139 minutes to run the full test suite. It can be executed in *quick* mode to just
140 run the most essential tests (around 1 900 test cases) in about 1 minute::
141
142 make test QUICKTEST=y
143
144 The :command:`script/mt` utility is also available to just execute one or
145 several testfiles. If a test fails, :command:`script/mt` reports the *diff*
146 comparison between expected and actual results. For instance, to only
147 execute :file:`testsuite/modules.50-cmds/470-variant.exp` testfile, run::
148
149 script/mt 50/470
150
151 Run :command:`script/mt` with ``--help`` option to get usage details and
152 syntax to select several testfiles.
153
154 .. _GitHub Actions: https://github.com/envmodules/modules/actions
155
156 .. _running-test-coverage:
157
158 Running test coverage
159 ~~~~~~~~~~~~~~~~~~~~~
160
161 Generating a report of lines that do not have test coverage can indicate where
162 to start contributing or what your tests should cover for the code changes you
163 submit.
164
165 Run ``make test COVERAGE=y`` which will automatically setup the `Nagelfar`_
166 Tcl code coverage tool in your ``modules`` development directory and
167 instrument the source Tcl scripts. Then the full testsuite will be run in
168 coverage mode and an annotated script will be produced for each Tcl script in
169 ``tcl`` source directory (``tcl/*.tcl_m``)::
170
171 make test COVERAGE=y
172 # then open tcl/*.tcl_m files and look for ';# Not covered' lines
173
174 The :command:`script/mt` utility may also be used to run the test suite in
175 coverage mode on full testsuite or on a few testfiles::
176
177 script/mt cov 70/{280,290}
178
179 .. _Nagelfar: http://nagelfar.sourceforge.net/
180
181 Running linter tests
182 ~~~~~~~~~~~~~~~~~~~~
183
184 Linter tools check code syntax and report issues and good practices to follow.
185 Modules uses `Nagelfar`_ to check syntax of Tcl scripts and `ShellCheck`_ to
186 lint sh, bash and ksh scripts.
187
188 Run ``make testlint`` to lint all sh, bash, ksh and Tcl scripts in your local
189 Modules repository.
190
191 The :command:`script/mt` utility may also be used to run the full *lint* test
192 suite or just specific testfiles. For instance to only lint Tcl scripts::
193
194 script/mt lint 00/030
195
196 .. _ShellCheck: https://www.shellcheck.net/
197
198 Check performances
199 ~~~~~~~~~~~~~~~~~~
200
201 The :command:`script/mb` utility checks from your local repository the
202 performances of major releases of Modules and current branch. Current ongoing
203 modifications are first stashed, then :command:`modulecmd.tcl` of the
204 releases and current branch are built. Different tests are run against each
205 version and the execution time of each test is reported in millisecond::
206
207 $ script/mb
208 | v4.1.4 | v4.3.1 | v4.5.3 | v4.7.1 | v5.1.1 | main |
209 ----------+----------+----------+----------+----------+----------+----------+
210 help | 9 | 12 | 12 | 15 | 16 | 16 |
211 avail | 61 | 67 | 76 | 82 | 91 | 86 |
212 avail2 | 11 | 16 | 19 | 21 | 23 | 23 |
213 avail3 | - | - | - | 120 | 128 | 130 |
214 whatis | 208 | 155 | 233 | 216 | 221 | 224 |
215 whatis2 | 10 | 15 | 17 | 20 | 21 | 22 |
216 whatis3 | - | - | - | 287 | 307 | 314 |
217 apropos | 208 | 153 | 222 | 210 | 220 | 223 |
218 load | 66 | 87 | 134 | 162 | 120 | 126 |
219 list | 24 | 23 | 33 | 22 | 25 | 25 |
220 unload | 46 | 24 | 25 | 29 | 31 | 31 |
221
222 It helps to verify that current work committed in local repository does not
223 impact performances on simple test scenarios. Run :command:`script/mb` with
224 ``--help`` option to get its usage details.
225
226 The ``profile`` mode may also be interesting to learn what are the internal
227 procedures of :command:`modulecmd.tcl` taking most of the execution time for
228 each test::
229
230 script/mb profile
231
232 Building the docs
233 ~~~~~~~~~~~~~~~~~
234
235 Build the docs in the ``doc`` directory using Sphinx::
236
237 cd doc
238 make html
239
240 Open ``_build/html/index.html`` in your browser to view the docs.
241
242 Read more about `Sphinx`_.
243
244 .. _Sphinx: https://www.sphinx-doc.org
245
246 .. _coding-conventions:
247
248 Coding conventions
249 ~~~~~~~~~~~~~~~~~~
250
251 * Maximum line length is 78 characters
252 * Use 3 spaces to indent code (do not use tab character)
253 * Adopt `Tcl minimal escaping style`_
254 * Procedure names: ``lowerCameCase``
255 * Variable names: ``no_case_at_all``
256 * Curly brace and square bracket placement::
257
258 if {![isStateDefined already_report]} {
259 setState already_report 1
260 }
261
262 * `No trailing space nor misspelling <commit-hooks_>`_
263
264 .. _Tcl minimal escaping style: https://wiki.tcl-lang.org/page/Tcl+Minimal+Escaping+Style
265
266 .. _code-comments:
267
268 Code comments
269 ~~~~~~~~~~~~~
270
271 Modules follows the code comment philosophy described by John Ousterhout in
272 `A Philosophy of Software Design`_:
273
274 * A comment should say something the code itself cannot: the reasoning
275 behind a choice, a non-obvious constraint or side effect, or a workaround
276 for a specific bug. Well-named identifiers and clear code already say
277 *what* is happening, so do not restate that in a comment.
278 * Write comments at a different level of detail than the code: either more
279 precise, spelling out units, boundary conditions or special values that
280 the code leaves implicit, or more abstract, giving the reader a
281 big-picture summary of what a block of code accomplishes.
282 * Document a procedure's interface from the caller's point of view, e.g.
283 what it does, its arguments and return value, and any non-obvious
284 behavior or ordering requirement, separately from implementation comments
285 that explain what a tricky part of the body does and why, not how.
286 * Keep comments next to the code they describe and update them whenever
287 that code changes, so they never drift out of sync. Prefer higher-level
288 comments, which stay accurate across minor code changes, over ones that
289 just restate implementation detail.
290 * Capture the *why* behind a non-obvious change as a comment in the code
291 itself, not only in the commit message, since a reader examining the code
292 later will not necessarily go digging through its history.
293
294 .. _A Philosophy of Software Design: https://web.stanford.edu/~ouster/cgi-bin/aposd.php
295
296 .. _commit-message-conventions:
297
298 Commit message conventions
299 ~~~~~~~~~~~~~~~~~~~~~~~~~~
300
301 * Prefix the subject line with the area touched, followed by a colon and a
302 lowercase verb, when a change is confined to that area, e.g. ``doc:``,
303 ``ts:`` (testsuite), ``install:`` (build system), ``gh:`` (GitHub
304 Actions), ``init:`` (shell init/completion scripts), ``script:``
305 (maintainer tooling), ``rpm:``, ``lint:``, ``vim:``, ``emacs:`` or
306 ``lib:``. Combine two areas with a slash, e.g. ``doc/ts:``, only when a
307 single prefix would be misleading. Leave the subject unprefixed, with a
308 capitalized verb, for changes to the core Tcl engine or its behavior.
309 * Use the imperative mood for the verb starting the subject, e.g. ``Add``
310 or ``doc: fix``, not ``Added``/``Adds`` or ``doc: fixed``/``fixes``.
311 * Do not end the subject with a period and try to keep it around 50 to 72
312 characters.
313 * Separate a commit body from its subject with a blank line and wrap it to
314 about the same width as the subject. Use it to explain *why* the change
315 is needed, following the `code comments guidelines <code-comments_>`_,
316 rather than restating what the diff already shows. Omit the body when the
317 subject line alone says everything there is to say.
318 * Reference an issue this commit resolves on its own line in the body,
319 e.g. ``Fixes #645`` or ``Closes #572``.
320 * Disclose `AI coding assistants <ai-coding-assistants_>`_ involvement, if
321 any, with an ``Assisted-by:`` trailer.
322 * `Sign-off your commits <developer-certificate-of-origin_>`_ with a
323 ``Signed-off-by:`` trailer, always as the last line of the commit
324 message.
325
326 .. _developer-certificate-of-origin:
327
328 Developer Certificate of Origin (DCO)
329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330
331 In order to ensure that all contributions are properly authorized and in
332 compliance with licensing requirements, Modules project follows the `Developer
333 Certificate of Origin (DCO)`_ process. The DCO is a lightweight mechanism to
334 certify that you, as a contributor, have the right to submit your code and
335 agree to the project’s licensing terms.
336
337 How to sign off your commits
338 """"""""""""""""""""""""""""
339
340 Every commit must include a ``Signed-off-by`` line, which certifies that the
341 contribution adheres to the DCO. You can do this by adding the following line
342 at the end of your commit message::
343
344 Signed-off-by: Your Name <[email protected]>
345
346 The name and email must match your Git configuration (``git config user.name``
347 and ``git config user.email``).
348
349 To simplify the process, you can use the ``-s`` flag of ``git`` command when
350 committing::
351
352 git commit -s -m "Your commit message"
353
354 Verifying DCO Compliance
355 """"""""""""""""""""""""
356
357 Modules repository automates checks to enforce the DCO. If your contribution
358 does not include the proper ``Signed-off-by`` line, the pull request check
359 will fail. You will need to amend your commit::
360
361 git commit --amend -s
362
363 .. _Developer Certificate of Origin (DCO): https://developercertificate.org/
364
365 .. _ai-coding-assistants:
366
367 AI coding assistants
368 ~~~~~~~~~~~~~~~~~~~~
369
370 Modules follows the Linux kernel's approach to AI-assisted contributions. AI
371 tools may help write a patch, but the human submitter remains fully
372 responsible for it: reviewing all AI-generated code, ensuring it complies
373 with the project's licensing requirements and `coding conventions
374 <coding-conventions_>`_, and testing it thoroughly.
375
376 AI agents must not add ``Signed-off-by`` tags. Only a human can certify the
377 `DCO <developer-certificate-of-origin_>`_, so the human submitter still adds
378 their own ``Signed-off-by`` line as usual.
379
380 When AI tools are used, disclose their involvement with an ``Assisted-by``
381 trailer at the end of the commit message::
382
383 Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
384
385 ``AGENT_NAME`` is the name of the AI tool or framework and ``MODEL_VERSION``
386 is the specific model version used. ``[TOOL1] [TOOL2]`` are optional
387 specialized analysis tools used alongside it (e.g. a linter); basic
388 development tools (git, make, editors) should not be listed. For example::
389
390 Assisted-by: Claude:claude-sonnet-5
391
392 .. _commit-hooks:
393
394 Commit hooks
395 ~~~~~~~~~~~~
396
397 A :command:`pre-commit` hook script is provided in the :file:`script`
398 directory of the project to help you check that the contribution made is free
399 of misspellings and trailing spaces. It requires the `codespell`_ utility that
400 checks for typos in any kind of files and the `Hunspell`_ utility that spell
401 checks documentation files. The :command:`pre-commit` could be enabled in your
402 local repository with following command::
403
404 ln -s ../../script/pre-commit .git/hooks/pre-commit
405
406 A :command:`commit-msg` hook script is also provided in the :file:`script`
407 directory of the project to help you check that your commit messages are free
408 of misspellings. It requires the `Hunspell`_ utility and could be enabled in
409 your local repository with following command::
410
411 ln -s ../../script/commit-msg .git/hooks/commit-msg
412
413 .. _codespell: https://github.com/codespell-project/codespell
414 .. _Hunspell: https://hunspell.github.io/
415
416 Emacs settings for coding conventions
417 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
418
419 This is an example Emacs configuration that adheres to the first two
420 coding conventions. You may wish to add this to your ``.emacs`` or
421 ``.emacs.d/`` to modify your tcl-mode::
422
423 (add-hook 'tcl-mode-hook
424 (lambda ()
425 (setq indent-tabs-mode nil)
426 (setq tcl-indent-level 3)
427 (setq tcl-continued-indent-level 3)
428 (font-lock-add-keywords nil '(("^[^\n]\\{79\\}\\(.*\\)$" 1
429 font-lock-warning-face prepend)))))
430
431 Submitting installation recipes
432 -------------------------------
433
434 * If you want to share your installation tips and tricks, efficient ways you
435 have to write or organize your modulefiles or some extension you made to the
436 ``module`` command please add a recipe to the cookbook section of the
437 documentation.
438 * Create a directory under ``doc/example`` and put there the extension code
439 or example modulefiles your recipe is about.
440 * Describe this recipe through a `reStructuredText`_ document in
441 ``doc/source/cookbook``. It is suggested to have an *Implementation*,
442 an *Installation* and an *Usage example* sections in that document to get
443 as much as possible the same document layout across recipes.
444 * `Submit a patch <submitting-patches_>`_ with all the above content.
445
446 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
447