Development workflow¶

Install
Tests
Run kw without installing it
Documentation
ShellCheck and shfmt

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 installing and removing.

Tests¶

To make sure our code is working as it is supposed to, we add 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. mk_test.sh and statistics_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 ajustments related to testing.

To see how to run individual test files, check our 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 code style guide, and makes use of tools, such as ShellCheck and 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:

Have shellcheck installed on your computer.
Install pre-commit.
Create a file named .pre-commit-config.yaml in your local kw repository with the following YAML code:

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/shellcheck
      args: [-e, "SC2016,SC2181,SC2034,SC2154", -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.

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

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(<q-args>)

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¶

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

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.