"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "CONTRIBUTING.rst" between
modules-5.1.1.tar.bz2 and modules-5.2.0.tar.bz2

About: The Environment Modules package provides for the dynamic modification of a user’s environment via modulefiles.

CONTRIBUTING.rst  (modules-5.1.1.tar.bz2)	:	CONTRIBUTING.rst  (modules-5.2.0.tar.bz2)
skipping to change at line 66		skipping to change at line 66
* Comply to the `coding conventions of this project <coding-conventions_>`_.		* Comply to the `coding conventions of this project <coding-conventions_>`_.
* Your Tcl code has to be compatible with Tcl version 8.5 and above (see		* Your Tcl code has to be compatible with Tcl version 8.5 and above (see
`Tcl 8.5 commands reference`_)		`Tcl 8.5 commands reference`_)
* Include tests that cover any code changes you make. Make sure the test fails		* Include tests that cover any code changes you make. Make sure the test fails
without your patch.		without your patch.
* `Run the tests <running-the-tests_>`_ and `verify coverage <running-test-cover age_>`_.		* `Run the tests <running-the-tests_>`_ and `verify coverage <running-test-cover age_>`_.
* Push your commits to GitHub and `create a pull request`_.		* Push your commits to GitHub and `create a pull request`_.
.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/lat est/git/commandlinegit.html#commit-your-changes		.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/lat est/git/commandlinegit.html#commit-your-changes
.. _create a pull request: https://help.github.com/articles/creating-a-pull-requ est/		.. _create a pull request: https://help.github.com/articles/creating-a-pull-requ est/
.. _Tcl 8.5 commands reference: https://www.tcl.tk/man/tcl8.5/TclCmd/contents.ht		.. _Tcl 8.5 commands reference: https://www.tcl-lang.org/man/tcl8.5/TclCmd/conte
m		nts.htm
.. _running-the-tests:
Design notes		Design notes
~~~~~~~~~~~~		~~~~~~~~~~~~
See the :ref:`design` for recent feature specifications. You may also find		See the :ref:`design` for recent feature specifications. You may also find
there some development howtos:		there some development howtos:
* :ref:`add-new-sub-command`		* :ref:`add-new-sub-command`
* :ref:`add-new-config-option`		* :ref:`add-new-config-option`
		.. _running-the-tests:
Running the tests		Running the tests
~~~~~~~~~~~~~~~~~		~~~~~~~~~~~~~~~~~
Run the basic test suite with::		Run the basic test suite with::
make test		make test
This only runs the tests for the current environment. `GitHub Actions`_ and		This only runs the tests for the current environment. `GitHub Actions`_ and
`Cirrus CI`_ will run the full suite when you submit your pull request.		`Cirrus CI`_ will run the full suite when you submit your pull request.
		There are more than 17 000 test cases thus it generally takes around 12
		minutes to run the full test suite. It can be executed in *quick* mode to just
		run the most essential tests in about 1 minute::
		make test QUICKTEST=y
		The :command:`script/mt` utility is also available to just execute one or
		several testfiles. If a test fails, :command:`script/mt` reports the *diff*
		comparison between expected and actual results. For instance, to only
		execute :file:`testsuite/modules.50-cmds/470-variant.exp` testfile, run::
		script/mt 50/470
		Run :command:`script/mt` with ``--help`` option to get usage details and
		syntax to select several testfiles.
.. _GitHub Actions: https://github.com/cea-hpc/modules/actions		.. _GitHub Actions: https://github.com/cea-hpc/modules/actions
.. _Cirrus CI: https://cirrus-ci.com/github/cea-hpc/modules		.. _Cirrus CI: https://cirrus-ci.com/github/cea-hpc/modules
.. _running-test-coverage:		.. _running-test-coverage:
Running test coverage		Running test coverage
~~~~~~~~~~~~~~~~~~~~~		~~~~~~~~~~~~~~~~~~~~~
Generating a report of lines that do not have test coverage can indicate where		Generating a report of lines that do not have test coverage can indicate where
to start contributing or what your tests should cover for the code changes you		to start contributing or what your tests should cover for the code changes you
skipping to change at line 110		skipping to change at line 126
Run ``make test COVERAGE=y`` which will automatically setup the `Nagelfar`_		Run ``make test COVERAGE=y`` which will automatically setup the `Nagelfar`_
Tcl code coverage tool in your ``modules`` development directory and		Tcl code coverage tool in your ``modules`` development directory and
instrument the source Tcl scripts. Then the full testsuite will be run in		instrument the source Tcl scripts. Then the full testsuite will be run in
coverage mode and an annotated script will be produced for each Tcl script in		coverage mode and an annotated script will be produced for each Tcl script in
``tcl`` source directory (``tcl/*.tcl_m``)::		``tcl`` source directory (``tcl/*.tcl_m``)::
make test COVERAGE=y		make test COVERAGE=y
# then open tcl/*.tcl_m files and look for ';# Not covered' lines		# then open tcl/*.tcl_m files and look for ';# Not covered' lines
		The :command:`script/mt` utility may also be used to run the test suite in
		coverage mode on full testsuite or on a few testfiles::
		script/mt cov 70/{280,290}
.. _Nagelfar: http://nagelfar.sourceforge.net/		.. _Nagelfar: http://nagelfar.sourceforge.net/
		Running linter tests
		~~~~~~~~~~~~~~~~~~~~
		Linter tools check code syntax and report issues and good practices to follow.
		Modules uses `Nagelfar`_ to check syntax of Tcl scripts and `ShellCheck`_ to
		lint sh, bash and ksh scripts.
		Run ``make testlint`` to lint all sh, bash, ksh and Tcl scripts in your local
		Modules repository.
		The :command:`script/mt` utility may also be used to run the full *lint* test
		suite or just specific testfiles. For instance to only lint Tcl scripts::
		script/mt lint 00/030
		.. _ShellCheck: https://www.shellcheck.net/
		Check performances
		~~~~~~~~~~~~~~~~~~
		The :command:`script/mb` utility checks from your local repository the
		performances of major releases of Modules and current branch. Current ongoing
		modifications are first stashed, then :command:`modulecmd.tcl` of the
		releases and current branch are built. Different tests are run against each
		version and the execution time of each test is reported in millisecond::
		$ script/mb
		| v4.1.4 | v4.3.1 | v4.5.3 | v4.7.1 | v5.1.1 | main |
		----------+----------+----------+----------+----------+----------+----------+
		help | 9 | 12 | 12 | 15 | 16 | 16 |
		avail | 61 | 67 | 76 | 82 | 91 | 86 |
		avail2 | 11 | 16 | 19 | 21 | 23 | 23 |
		avail3 | - | - | - | 120 | 128 | 130 |
		whatis | 208 | 155 | 233 | 216 | 221 | 224 |
		whatis2 | 10 | 15 | 17 | 20 | 21 | 22 |
		whatis3 | - | - | - | 287 | 307 | 314 |
		apropos | 208 | 153 | 222 | 210 | 220 | 223 |
		load | 66 | 87 | 134 | 162 | 120 | 126 |
		list | 24 | 23 | 33 | 22 | 25 | 25 |
		unload | 46 | 24 | 25 | 29 | 31 | 31 |
		It helps to verify that current work committed in local repository does not
		impact performances on simple test scenarios. Run :command:`script/mb` with
		``--help`` option to get its usage details.
		The ``profile`` mode may also be interesting to learn what are the internal
		procedures of :command:`modulecmd.tcl` taking most of the execution time for
		each test::
		script/mb profile
Building the docs		Building the docs
~~~~~~~~~~~~~~~~~		~~~~~~~~~~~~~~~~~
Build the docs in the ``doc`` directory using Sphinx::		Build the docs in the ``doc`` directory using Sphinx::
cd doc		cd doc
make html		make html
Open ``_build/html/index.html`` in your browser to view the docs.		Open ``_build/html/index.html`` in your browser to view the docs.
End of changes. 5 change blocks.
4 lines changed or deleted		76 lines changed or added

---