| 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 |
|