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