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