.. _CONTRIBUTING: Contributing ============ Thank you for considering contributing to Modules! Support questions ----------------- Please use the `modules-interest mailing list`_ for questions. Do not use the issue tracker for this. .. _modules-interest mailing list: https://sourceforge.net/projects/modules/lists/modules-interest Asking for new features ----------------------- Please submit your new feature wishes first to the `modules-interest mailing list`_. Discussion will help to clarify your needs and sometimes the wanted feature may already be available. Reporting issues ---------------- * Describe what you expected to happen. * If possible, include a `minimal, complete, and verifiable example`_ to help us identify the issue. * Describe what actually happened. Run the ``module`` command in ``--debug`` mode and include all the debug output obtained in your report. * Provide the current configuration and state of your Modules installation by running the ``module config --dump-state`` command. * Provide the name and content of the modulefiles you try to manipulate. .. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve .. _submitting-patches: Submitting patches ------------------ * Whether your patch is supposed to solve a bug or add a new feature, please include tests. In case of a bug, explain clearly under which circumstances it happens and make sure the test fails without your patch. * If you are not yet familiar with the ``git`` command and `GitHub`_, please read the `don't be afraid to commit`_ tutorial. .. _GitHub: https://github.com/ .. _don't be afraid to commit: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/index.html Start coding ~~~~~~~~~~~~ * Create a branch to identify the issue or feature you would like to work on * Using your favorite editor, make your changes, `committing as you go`_. * Comply to the `coding conventions of this project <coding-conventions_>`_. * Include tests that cover any code changes you make. Make sure the test fails without your patch. * `Run the tests <running-the-tests_>`_ and `verify coverage <running-test-coverage_>`_. * Push your commits to GitHub and `create a pull request`_. .. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes .. _create a pull request: https://help.github.com/articles/creating-a-pull-request/ .. _running-the-tests: Running the tests ~~~~~~~~~~~~~~~~~ Run the basic test suite with:: make test This only runs the tests for the current environment. `Travis-CI`_ and `AppVeyor`_ will run the full suite when you submit your pull request. .. _Travis-CI: https://travis-ci.org/cea-hpc/modules/ .. _AppVeyor: https://ci.appveyor.com/project/xdelaruelle/modules-a6nha .. _running-test-coverage: Running test coverage ~~~~~~~~~~~~~~~~~~~~~ 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 submit. Run ``make test COVERAGE=y`` which will automatically setup the `Nagelfar`_ Tcl code coverage tool in your ``modules`` development directory. Then the full testsuite will be run in coverage mode and a ``modulecmd-test.tcl_m`` annotated script will be produced:: make test COVERAGE=y # then open modulecmd-test.tcl_m and look for ';# Not covered' lines .. _Nagelfar: http://nagelfar.sourceforge.net/ Building the docs ~~~~~~~~~~~~~~~~~ Build the docs in the ``doc`` directory using Sphinx:: cd doc make html Open ``_build/html/index.html`` in your browser to view the docs. Read more about `Sphinx`_. .. _Sphinx: https://www.sphinx-doc.org .. _coding-conventions: Coding conventions ~~~~~~~~~~~~~~~~~~ * Maximum line length is 78 characters * Use 3 spaces to indent code (do not use tab character) * Adopt `Tcl minimal escaping style`_ * Procedure names: ``lowerCameCase`` * Variable names: ``nocaseatall`` * Curly brace and square bracket placement:: if {![info exists ::g_already_report]} { set ::g_already_report 1 } .. _Tcl minimal escaping style: https://wiki.tcl-lang.org/page/Tcl+Minimal+Escaping+Style Emacs settings for coding conventions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is an example emacs configuration that adheres to the first two coding conventions. You may wish to add this to your ``.emacs`` or ``.emacs.d/`` to modify your tcl-mode:: (add-hook 'tcl-mode-hook (lambda () (setq indent-tabs-mode nil) (setq tcl-indent-level 3) (setq tcl-continued-indent-level 3) (font-lock-add-keywords nil '(("^[^\n]\\{79\\}\\(.*\\)$" 1 font-lock-warning-face prepend))))) Submitting installation recipes ------------------------------- * If you want to share your installation tips and tricks, efficient ways you have to write or organize your modulefiles or some extension you made to the ``module`` command please add a recipe to the cookbook section of the documentation. * Create a directory under ``doc/example`` and put there the extension code or example modulefiles your recipe is about. * Describe this recipe through a `reStructuredText`_ document in ``doc/source/cookbook``. It is suggested to have an *Implementation*, an *Installation* and an *Usage example* sections in that document to get as much as possible the same document layout across recipes. * `Submit a patch <submitting-patches_>`_ with all the above content. .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html