| 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 |
Submitting patches |
| 56 |
================== |
| 57 |
|
| 58 |
* Whether your patch is supposed to solve a bug or add a new feature, |
| 59 |
please include tests. In case of a bug, explain clearly under which |
| 60 |
circumstances it happens and make sure the test fails without your |
| 61 |
patch. |
| 62 |
|
| 63 |
* If you are not yet familiar with the "git" command and GitHub, |
| 64 |
please read the don't be afraid to commit tutorial. |
| 65 |
|
| 66 |
|
| 67 |
Start coding |
| 68 |
------------ |
| 69 |
|
| 70 |
* Create a branch to identify the issue or feature you would like to |
| 71 |
work on |
| 72 |
|
| 73 |
* Using your favorite editor, make your changes, committing as you go. |
| 74 |
|
| 75 |
* Comply to the coding conventions of this project. |
| 76 |
|
| 77 |
* Your Tcl code has to be compatible with Tcl version 8.5 and above |
| 78 |
(see Tcl 8.5 commands reference) |
| 79 |
|
| 80 |
* Include tests that cover any code changes you make. Make sure the |
| 81 |
test fails without your patch. |
| 82 |
|
| 83 |
* Run the tests and verify coverage. |
| 84 |
|
| 85 |
* Sign-off your commits. |
| 86 |
|
| 87 |
* Push your commits to GitHub and create a pull request. |
| 88 |
|
| 89 |
|
| 90 |
Developer notes |
| 91 |
--------------- |
| 92 |
|
| 93 |
See the Design notes for recent feature specifications. Some |
| 94 |
development howtos are also available: |
| 95 |
|
| 96 |
* Add new module sub-command |
| 97 |
|
| 98 |
* Add new configuration option |
| 99 |
|
| 100 |
|
| 101 |
Running the tests |
| 102 |
----------------- |
| 103 |
|
| 104 |
Run the basic test suite with: |
| 105 |
|
| 106 |
make test |
| 107 |
|
| 108 |
This only runs the tests for the current environment. GitHub Actions |
| 109 |
and Cirrus CI will run the full suite when you submit your pull |
| 110 |
request. |
| 111 |
|
| 112 |
There are more than 17 000 test cases thus it generally takes around |
| 113 |
12 minutes to run the full test suite. It can be executed in *quick* |
| 114 |
mode to just run the most essential tests in about 1 minute: |
| 115 |
|
| 116 |
make test QUICKTEST=y |
| 117 |
|
| 118 |
The **script/mt** utility is also available to just execute one or |
| 119 |
several testfiles. If a test fails, **script/mt** reports the *diff* |
| 120 |
comparison between expected and actual results. For instance, to only |
| 121 |
execute "testsuite/modules.50-cmds/470-variant.exp" testfile, run: |
| 122 |
|
| 123 |
script/mt 50/470 |
| 124 |
|
| 125 |
Run **script/mt** with "--help" option to get usage details and syntax |
| 126 |
to select several testfiles. |
| 127 |
|
| 128 |
|
| 129 |
Running test coverage |
| 130 |
--------------------- |
| 131 |
|
| 132 |
Generating a report of lines that do not have test coverage can |
| 133 |
indicate where to start contributing or what your tests should cover |
| 134 |
for the code changes you submit. |
| 135 |
|
| 136 |
Run "make test COVERAGE=y" which will automatically setup the Nagelfar |
| 137 |
Tcl code coverage tool in your "modules" development directory and |
| 138 |
instrument the source Tcl scripts. Then the full testsuite will be run |
| 139 |
in coverage mode and an annotated script will be produced for each Tcl |
| 140 |
script in "tcl" source directory ("tcl/*.tcl_m"): |
| 141 |
|
| 142 |
make test COVERAGE=y |
| 143 |
# then open tcl/*.tcl_m files and look for ';# Not covered' lines |
| 144 |
|
| 145 |
The **script/mt** utility may also be used to run the test suite in |
| 146 |
coverage mode on full testsuite or on a few testfiles: |
| 147 |
|
| 148 |
script/mt cov 70/{280,290} |
| 149 |
|
| 150 |
|
| 151 |
Running linter tests |
| 152 |
-------------------- |
| 153 |
|
| 154 |
Linter tools check code syntax and report issues and good practices to |
| 155 |
follow. Modules uses Nagelfar to check syntax of Tcl scripts and |
| 156 |
ShellCheck to lint sh, bash and ksh scripts. |
| 157 |
|
| 158 |
Run "make testlint" to lint all sh, bash, ksh and Tcl scripts in your |
| 159 |
local Modules repository. |
| 160 |
|
| 161 |
The **script/mt** utility may also be used to run the full *lint* test |
| 162 |
suite or just specific testfiles. For instance to only lint Tcl |
| 163 |
scripts: |
| 164 |
|
| 165 |
script/mt lint 00/030 |
| 166 |
|
| 167 |
|
| 168 |
Check performances |
| 169 |
------------------ |
| 170 |
|
| 171 |
The **script/mb** utility checks from your local repository the |
| 172 |
performances of major releases of Modules and current branch. Current |
| 173 |
ongoing modifications are first stashed, then **modulecmd.tcl** of the |
| 174 |
releases and current branch are built. Different tests are run against |
| 175 |
each version and the execution time of each test is reported in |
| 176 |
millisecond: |
| 177 |
|
| 178 |
$ script/mb |
| 179 |
| v4.1.4 | v4.3.1 | v4.5.3 | v4.7.1 | v5.1.1 | main | |
| 180 |
----------+----------+----------+----------+----------+----------+----------+ |
| 181 |
help | 9 | 12 | 12 | 15 | 16 | 16 | |
| 182 |
avail | 61 | 67 | 76 | 82 | 91 | 86 | |
| 183 |
avail2 | 11 | 16 | 19 | 21 | 23 | 23 | |
| 184 |
avail3 | - | - | - | 120 | 128 | 130 | |
| 185 |
whatis | 208 | 155 | 233 | 216 | 221 | 224 | |
| 186 |
whatis2 | 10 | 15 | 17 | 20 | 21 | 22 | |
| 187 |
whatis3 | - | - | - | 287 | 307 | 314 | |
| 188 |
apropos | 208 | 153 | 222 | 210 | 220 | 223 | |
| 189 |
load | 66 | 87 | 134 | 162 | 120 | 126 | |
| 190 |
list | 24 | 23 | 33 | 22 | 25 | 25 | |
| 191 |
unload | 46 | 24 | 25 | 29 | 31 | 31 | |
| 192 |
|
| 193 |
It helps to verify that current work committed in local repository |
| 194 |
does not impact performances on simple test scenarios. Run |
| 195 |
**script/mb** with "--help" option to get its usage details. |
| 196 |
|
| 197 |
The "profile" mode may also be interesting to learn what are the |
| 198 |
internal procedures of **modulecmd.tcl** taking most of the execution |
| 199 |
time for each test: |
| 200 |
|
| 201 |
script/mb profile |
| 202 |
|
| 203 |
|
| 204 |
Building the docs |
| 205 |
----------------- |
| 206 |
|
| 207 |
Build the docs in the "doc" directory using Sphinx: |
| 208 |
|
| 209 |
cd doc |
| 210 |
make html |
| 211 |
|
| 212 |
Open "_build/html/index.html" in your browser to view the docs. |
| 213 |
|
| 214 |
Read more about Sphinx. |
| 215 |
|
| 216 |
|
| 217 |
Coding conventions |
| 218 |
------------------ |
| 219 |
|
| 220 |
* Maximum line length is 78 characters |
| 221 |
|
| 222 |
* Use 3 spaces to indent code (do not use tab character) |
| 223 |
|
| 224 |
* Adopt Tcl minimal escaping style |
| 225 |
|
| 226 |
* Procedure names: "lowerCameCase" |
| 227 |
|
| 228 |
* Variable names: "no_case_at_all" |
| 229 |
|
| 230 |
* Curly brace and square bracket placement: |
| 231 |
|
| 232 |
if {![isStateDefined already_report]} { |
| 233 |
setState already_report 1 |
| 234 |
} |
| 235 |
|
| 236 |
* No trailing space nor misspelling |
| 237 |
|
| 238 |
|
| 239 |
Developer Certificate of Origin (DCO) |
| 240 |
------------------------------------- |
| 241 |
|
| 242 |
In order to ensure that all contributions are properly authorized and |
| 243 |
in compliance with licensing requirements, Modules project follows the |
| 244 |
Developer Certificate of Origin (DCO) process. The DCO is a |
| 245 |
lightweight mechanism to certify that you, as a contributor, have the |
| 246 |
right to submit your code and agree to the project’s licensing terms. |
| 247 |
|
| 248 |
|
| 249 |
How to sign off your commits |
| 250 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 251 |
|
| 252 |
Every commit must include a "Signed-off-by" line, which certifies that |
| 253 |
the contribution adheres to the DCO. You can do this by adding the |
| 254 |
following line at the end of your commit message: |
| 255 |
|
| 256 |
Signed-off-by: Your Name <[email protected]> |
| 257 |
|
| 258 |
The name and email must match your Git configuration ("git config |
| 259 |
user.name" and "git config user.email"). |
| 260 |
|
| 261 |
To simplify the process, you can use the "-s" flag of "git" command |
| 262 |
when committing: |
| 263 |
|
| 264 |
git commit -s -m "Your commit message" |
| 265 |
|
| 266 |
|
| 267 |
Verifying DCO Compliance |
| 268 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
| 269 |
|
| 270 |
Modules repository automates checks to enforce the DCO. If your |
| 271 |
contribution does not include the proper "Signed-off-by" line, the |
| 272 |
pull request check will fail. You will need to amend your commit: |
| 273 |
|
| 274 |
git commit --amend -s |
| 275 |
|
| 276 |
|
| 277 |
Commit hooks |
| 278 |
------------ |
| 279 |
|
| 280 |
A **pre-commit** hook script is provided in the "script" directory of |
| 281 |
the project to help you check that the contribution made is free of |
| 282 |
misspellings and trailing spaces. It requires the codespell utility |
| 283 |
that checks for typos in any kind of files and the Hunspell utility |
| 284 |
that spell checks documentation files. The **pre-commit** could be |
| 285 |
enabled in your local repository with following command: |
| 286 |
|
| 287 |
ln -s ../../script/pre-commit .git/hooks/pre-commit |
| 288 |
|
| 289 |
A **commit-msg** hook script is also provided in the "script" |
| 290 |
directory of the project to help you check that your commit messages |
| 291 |
are free of misspellings. It requires the Hunspell utility and could |
| 292 |
be enabled in your local repository with following command: |
| 293 |
|
| 294 |
ln -s ../../script/commit-msg .git/hooks/commit-msg |
| 295 |
|
| 296 |
|
| 297 |
Emacs settings for coding conventions |
| 298 |
------------------------------------- |
| 299 |
|
| 300 |
This is an example Emacs configuration that adheres to the first two |
| 301 |
coding conventions. You may wish to add this to your ".emacs" or |
| 302 |
".emacs.d/" to modify your tcl-mode: |
| 303 |
|
| 304 |
(add-hook 'tcl-mode-hook |
| 305 |
(lambda () |
| 306 |
(setq indent-tabs-mode nil) |
| 307 |
(setq tcl-indent-level 3) |
| 308 |
(setq tcl-continued-indent-level 3) |
| 309 |
(font-lock-add-keywords nil '(("^[^\n]\\{79\\}\\(.*\\)$" 1 |
| 310 |
font-lock-warning-face prepend))))) |
| 311 |
|
| 312 |
|
| 313 |
Submitting installation recipes |
| 314 |
=============================== |
| 315 |
|
| 316 |
* If you want to share your installation tips and tricks, efficient |
| 317 |
ways you have to write or organize your modulefiles or some |
| 318 |
extension you made to the "module" command please add a recipe to |
| 319 |
the cookbook section of the documentation. |
| 320 |
|
| 321 |
* Create a directory under "doc/example" and put there the extension |
| 322 |
code or example modulefiles your recipe is about. |
| 323 |
|
| 324 |
* Describe this recipe through a reStructuredText document in |
| 325 |
"doc/source/cookbook". It is suggested to have an *Implementation*, |
| 326 |
an *Installation* and an *Usage example* sections in that document |
| 327 |
to get as much as possible the same document layout across recipes. |
| 328 |
|
| 329 |
* Submit a patch with all the above content. |