Debian Codegraph @

doc/build/CONTRIBUTING.txt

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