======================== Development workflow ======================== .. contents:: :depth: 1 :local: :backlinks: none .. highlight:: console kw is developed using Git and is hosted at Github. If you want to understand our development workflow better, clone the repository to have a local copy:: git clone https://github.com/kworkflow/kworkflow.git Install ------- Installing kw is one of the first steps to understanding its development workflow. After cloning the repository, read the page related to :ref:`installing and removing`. Tests ----- To make sure our code is working as it is supposed to, we add :ref:`tests` to check that. All our tests can be found in the `tests` folder. Notice that every test file name ends with test before the .sh extension (i.e. `build_test.sh` and `deploy_test.sh`). This is done so that the `run_tests.sh` file can detect those tests and run or list them. Unit tests ========== Unit testing is an essential part of our development workflow and we use the `shUnit2 `_ framework to write our tests. Ideally, every new function should have a test related to it. So, if you're working on a new feature, added a new function, or changed the behavior of an existing one, it's fundamental to make the necessary adjustments related to testing. To see how to run individual test files, check our :ref:`page on that`. Run kw without installing it ---------------------------- Apart from using the installed version of kw, you can also use your local version by going into it and running `./kw` with any other option you want, just like you would do when you run kw that is installed in your machine. For instance, suppose you changed the `help.sh` file and want to see if everything's working as expected. Inside the kw directory you're working on, you can just invoke:: ./kw help This is a convenient option when you're developing for kw and don't want to install it every time you make a new change to see the result. Running `./kw b` or `./kw d` won't work, though, since these two options require you to be inside a repository. Documentation ------------- As important as writing tests is documenting things. Our documentation is located in the `documentation` folder, and we use `Sphinx `_ to create it. Whether you changed the way a command behaves or added a new feature, modify the documentation accordingly and preferably with examples. Also, in the source code, we tend to comment on top of each function, explaining its usage. ShellCheck and shfmt -------------------- kw follows its own :ref:`code style guide`, and makes use of tools, such as ShellCheck and :ref:`shfmt`, to make sure this code style is being followed. Git pre-commit hook =================== A very handy way to ensure that your code is well-formatted and follows our standards is to have a pre-commit hook configured to run the aforementioned tools before committing. This may, for example, prevent code with bad syntax and wrong formatting from even being committed before having these things fixed. To configure this Git pre-commit hook: 0. Have shellcheck installed on your computer. 1. Install `pre-commit `_. 2. Create a file named `.pre-commit-config.yaml` in your local kw repository with the following YAML code: .. code-block:: yaml repos: - repo: local hooks: - id: shfmt name: shfmt minimum_pre_commit_version: 2.4.0 language: golang additional_dependencies: [mvdan.cc/sh/v3/cmd/shfmt@v3.3.0] entry: shfmt args: [-w, -i=2, -ln=bash, -fn, -ci, -sr] types: [shell] - id: shellcheck name: shellcheck language: script entry: /usr/bin/env shellcheck args: [-e, "SC2016,SC2181,SC2034,SC2154,SC2001,SC1090,SC1091,SC2120", -x, --shell=bash] types: [shell] .. note:: Notice that the pre-commit hook above sets a shfmt version, which is the same one we use in the Github actions. 3. Then, run:: pre-commit install The next time you try to commit your work, your pre-commit hook will run both shellcheck and shfmt, and warn you of any errors you may have made. Kwreview ======== Another way to have your code checked against ``shfmt`` and ``shellcheck`` is to use ``scripts/kwreview.sh``. By default, it will check your current patch (i.e. what has changed since the branch unstable) and print ``shellcheck``'s warnings and ``shfmt``'s warnings as diffs. Use ``kwreview -w`` to apply ``shfmt``'s changes to the files. If you supply it with path to shell files, it will analyse those. Make sure you have ``shfmt``, ``shellcheck`` and ``reviewdog`` installed (see :ref:`dependencies_label`). For vim users, it is possible to use ``kwreview.sh`` to populate the `quickfix `_ (or locations) window, making it easy to navigate the warnings and errors. As an example, consider adding the following lines to your ``.vimrc``:: function Kwreview(...) let arg = get(a:, 1, "") let &l:makeprg="scripts/kwreview.sh " . arg make execute ":e" endfunction command -nargs=* Kwreview :call Kwreview() Now you can call ``kwreview.sh`` with the vim command ``:Kwreview`` (notice the upper case initial) and navigate the errors/warnings with ``:copen``, ``:cn``, ``:cp``, etc. .. _dependencies_label: Dependencies ============ Installing ShellCheck ~~~~~~~~~~~~~~~~~~~~~ Shellcheck is available as a package for most distributions. On Debian based distros, use ``sudo apt install shellcheck``. On Arch based distros, use ``sudo pacman -S shellcheck``. Installing shfmt ~~~~~~~~~~~~~~~~ To install shfmt, ``go`` must be installed. On Debian based distros:: sudo apt install golang On arch based distros:: sudo pacman -S go With go installed, run the following command to install shfmt:: GO111MODULE=on go get mvdan.cc/sh/v3/cmd/shfmt More information can be found in their `github page `__. Installing pre-commit ~~~~~~~~~~~~~~~~~~~~~ ``pre-commit`` is available as a package for some distributions. On Debian based distros, try using ``sudo apt install pre-commit``. On Arch based distros, use ``sudo pacman -S python-pre-commit``. If that doesn't work, you can install it using pip with ``pip install pre-commit``. Installing reviewdog ~~~~~~~~~~~~~~~~~~~~ To install reviewdog, run the following command:: curl -sfL https://raw.githubusercontent.com/reviewdog/reviewdog/master/install.sh | sh -s -- -b This will install reviewdog in the directory at ``path``. Make sure this directory is in your ``PATH`` environmental variable, so that reviewdog is executable from any directory. For example, you can install it in:: $HOME/bin/ And add the following line to you shell configuration file (e.g. ``~/.profile``):: if [ -d "$HOME/bin" ] ; then PATH="$HOME/bin:$PATH" fi Check out reviewdog's `github page `__ for other installation options.