Debian Codegraph @

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