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