Contributing

Contributing to Nut

This guide gives some tips about modifing and testing Nut.

Debugging a macro

When writing a macro, one may get lost in inception of folders, volumes paths, environments variables, settings overloading, ... To get some insight about what is going on, you may want to turn logs on:

nut new_macro
nut --macro=new_macro --logs  # use --macro to allow additional flags, such as --logs

You may also want to run some sanity checks, such as printing the path of the current folder, listing files, and printing environment variables:

nut --extend-macro=new_macro --logs --exec='pwd && ls && printenv'
nut --extend-macro=new_macro --logs --exec='echo $VAR'  # use simple quotes if you want the variable to be interpreted in the container

Testing new values for the configuration

To try out new nut configurations for this project, the easiest way is to create a file nut.override.yml in project root folder, and override original settings there. For example:

# nut.override.yml
syntax_version: "7"
based_on:
    nut_file_path: nut.yml
docker_image: new_contributor/awesome_new_image

The advantage is that this file is ignored by git, so it won't be shared in commits. This way, each contributor can have its own set of private settings.

This new settings may prevent you from building Nut with nut build. In this case, you may want to specify those settings for a macro:

# nut.override.yml
syntax_version: "7"
based_on:
    nut_file_path: nut.yml
macros:
    dev:
        usage: use with --exec when testing new features
        docker_image: new_contributor/awesome_new_image

# nut.yml
syntax_version: "6"
docker_image: golang:1.6
macros:
    build:
        usage: build the project
        actions:
        - go build -o nut
        - echo Done

In this configuration, nut build will not be affected by nut.override.yml, and you can test the new configuration with

nut dev
nut --extend-macro=dev --exec='echo Run some quick tests.'

Releasing

The branch manualbuild contains a folder ./release/, which holds binaries for common platforms. Those binaries are shipped in nut-bin NPM package. The best way to update those files is to switch to the branch manualbuild, and to call nut release. This macro will insert the date and the ID of the commit into the source code, compile to the release folder, and then restore the original source code.

This gives a nice helper:

$ nut
NAME:
   nut - the development environment, containerized

USAGE:
   nut [global options] command [command options] [arguments...]
   
VERSION:
   0.1.4 dev. Build from commit 41cf72f12648a67088079dc54dc28c492a90c12f, at 04h39min17sec on 2016/06/28 (PDT)
   
COMMANDS:
...