From b7f10dc55b7632ff15a632e9c8679dd568516bee Mon Sep 17 00:00:00 2001 From: Filippo Squillace Date: Wed, 11 May 2016 22:40:12 +0100 Subject: [PATCH] :memo: Update CONTRIBUTING.md and change unit tests file names --- .travis.yml | 2 +- CONTRIBUTING.md | 91 ++++++++++++++++++++++++++-- tests/shunit2 | 59 ++++++++++++------ tests/{test_cli.sh => test-cli.sh} | 0 tests/{test_core.sh => test-core.sh} | 0 tests/{test_util.sh => test-util.sh} | 0 tests/{test_all.sh => unit-tests.sh} | 3 +- 7 files changed, 128 insertions(+), 27 deletions(-) mode change 100755 => 100644 tests/shunit2 rename tests/{test_cli.sh => test-cli.sh} (100%) rename tests/{test_core.sh => test-core.sh} (100%) rename tests/{test_util.sh => test-util.sh} (100%) rename tests/{test_all.sh => unit-tests.sh} (51%) diff --git a/.travis.yml b/.travis.yml index 570a311..3eb7b32 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,7 +10,7 @@ install: #- JUNEST_HOME=~/.junest-x86 junest -a x86 -- echo "Installing JuNest (\$(uname -m))" script: - - ./tests/test_all.sh + - ./tests/unit-tests.sh - junest --check ./bin/junest - yes | junest --delete - JUNEST_HOME=~/.junest-arm junest --check ./bin/junest --skip-root-tests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fee979e..c5b62fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,5 @@ -# Contributing to JuNest # +Contributing to JuNest +===================== First off, thanks for taking the time to contribute! @@ -18,6 +19,8 @@ feel free to propose changes to this document in a pull request. - [Documentation Styleguide](#documentation-styleguide) - [Shell Styleguide](#shell-styleguide) +- [Versioning](#versioning) + ## How Can I Contribute? ## ### Reporting Bugs ### @@ -135,6 +138,10 @@ All JuNest issues are tracked as [GitHub issues](https://guides.github.com/featu #### Pull Requests #### +* Fork the repo and create your feature branch from ***dev***. +* If you make significant changes, please add tests too. + Get familiar with [shunit](https://github.com/kward/shunit2). +* If you've changed APIs, please update the documentation * Follow the [Shell styleguide](#shell-styleguide). * Document new code based on the [Documentation Styleguide](#documentation-styleguide). @@ -143,15 +150,23 @@ All JuNest issues are tracked as [GitHub issues](https://guides.github.com/featu * Send a [GitHub Pull Request to JuNest](https://github.com/fsquillace/junest/compare/dev...) with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). * Put **dev as the base branch** and NOT the master one. +#### Unit Tests #### +To run unit tests: +```sh +./tests/unit-tests.sh +``` + +#### Integration Tests #### +Generally, there is no need to run integration tests locally +since [Travis](https://travis-ci.org/fsquillace/junest) will run as +soon as the pull request gets created. + ## Styleguides ## ### Git Commit Messages ### -* Use the present tense ("Add feature" not "Added feature") -* Use the imperative mood ("Move cursor to..." not "Moves cursor to...") -* Limit the first line to 72 characters or less +* Follow the [seven rules](http://chris.beams.io/posts/git-commit/#seven-rules) of a great Git commit message * Reference issues and pull requests liberally -* When only changing documentation, include `[ci skip]` in the commit description * Consider starting the commit message with an applicable emoji: * :art: `:art:` when improving the format/structure of the code * :racehorse: `:racehorse:` when improving performance @@ -168,6 +183,7 @@ All JuNest issues are tracked as [GitHub issues](https://guides.github.com/featu * :arrow_up: `:arrow_up:` when upgrading dependencies * :arrow_down: `:arrow_down:` when downgrading dependencies * :shirt: `:shirt:` when removing linter warnings + * :package: `:package:` when bumping the version ### Documentation Styleguide ### @@ -177,3 +193,68 @@ All JuNest issues are tracked as [GitHub issues](https://guides.github.com/featu * Use [google shell styleguide](https://google.github.io/styleguide/shell.xml) +#### Function documentation #### +For function documentation follows the example below: + + ####################################### + # Cleanup files from the backup dir. + # + # Globals: + # VAR1 (RO,bool) : `my_func` access to VAR1. + # VAR2 (WO) : `my_func` change the value of VAR2. + # VAR3 (RW) : `my_func` read and write to VAR3. + # Arguments: + # arg1 ($1,int) : Directory to cleanup. + # arg2 ($2-) : Command to execute for the cleanup. + # Returns: + # 0 : Cleanup completed successfully. + # 101 : Backup directory is not readable. + # $NOT_DIR_ERROR : Backup directory is not a directory. + # Output: + # None + ####################################### + my_func() { + local arg1=$1 + shift + local arg2=$@ + ... + } + +The documentation is divided by a description of the function, a `Globals`, +`Arguments`, `Returns` and `Output` sections. If a section does not need details +use the word `None` inside of it. + +`Globals` section provides all global variables that interact with the function. + +`Arguments` section provides the list of arguments to pass to the function. Use +the parenthesis to indicate the position of the arguments: + +- `$1` : Argument is in position one. +- `$2-` : Argument takes all args from position two up to the end. +- `$@` : Argument takes all args. +- `$3?` : Argument is optional. + +Variables defined in `Globals` and `Arguments` sections can have the following +types: + +- `int` : Integer variable. +- `str` : String variable (default). +- `bool` : Bool variable. + +`Returns` section contains the exit status of the function. + +`Output` section describe the string printed to stdout. + +## Versioning ## + +* JuNest uses the following [semantic versioning](http://semver.org/) + +### Public API ### + +The public API refers to the following parts of JuNest system: + +- JuNest script CLI + +Any potential code change that cause backwards incompatible changes to the +public API requires the major version to be incremented. + diff --git a/tests/shunit2 b/tests/shunit2 old mode 100755 new mode 100644 index 8862ffd..d6e7503 --- a/tests/shunit2 +++ b/tests/shunit2 @@ -1,5 +1,5 @@ #! /bin/sh -# $Id: shunit2 335 2011-05-01 20:10:33Z kate.ward@forestent.com $ +# $Id$ # vim:et:ft=sh:sts=2:sw=2 # # Copyright 2008 Kate Ward. All Rights Reserved. @@ -15,20 +15,31 @@ # return if shunit already loaded [ -n "${SHUNIT_VERSION:-}" ] && exit 0 +SHUNIT_VERSION='2.1.7pre' -SHUNIT_VERSION='2.1.6' - +# return values that scripts can use SHUNIT_TRUE=0 SHUNIT_FALSE=1 SHUNIT_ERROR=2 -# enable strict mode by default -SHUNIT_STRICT=${SHUNIT_STRICT:-${SHUNIT_TRUE}} - +# logging functions _shunit_warn() { echo "shunit2:WARN $@" >&2; } _shunit_error() { echo "shunit2:ERROR $@" >&2; } _shunit_fatal() { echo "shunit2:FATAL $@" >&2; exit ${SHUNIT_ERROR}; } +# determine some reasonable command defaults +__SHUNIT_UNAME_S=`uname -s` +case "${__SHUNIT_UNAME_S}" in + BSD) __SHUNIT_EXPR_CMD='gexpr' ;; + *) __SHUNIT_EXPR_CMD='expr' ;; +esac + +# commands a user can override if needed +SHUNIT_EXPR_CMD=${SHUNIT_EXPR_CMD:-${__SHUNIT_EXPR_CMD}} + +# enable strict mode by default +SHUNIT_STRICT=${SHUNIT_STRICT:-${SHUNIT_TRUE}} + # specific shell checks if [ -n "${ZSH_VERSION:-}" ]; then setopt |grep "^shwordsplit$" >/dev/null @@ -51,19 +62,24 @@ __SHUNIT_MODE_STANDALONE='standalone' __SHUNIT_PARENT=${SHUNIT_PARENT:-$0} # set the constants readonly -shunit_constants_=`set |grep '^__SHUNIT_' |cut -d= -f1` -echo "${shunit_constants_}" |grep '^Binary file' >/dev/null && \ - shunit_constants_=`set |grep -a '^__SHUNIT_' |cut -d= -f1` -for shunit_constant_ in ${shunit_constants_}; do - shunit_ro_opts_='' - case ${ZSH_VERSION:-} in - '') ;; # this isn't zsh - [123].*) ;; # early versions (1.x, 2.x, 3.x) - *) shunit_ro_opts_='-g' ;; # all later versions. declare readonly globally - esac - readonly ${shunit_ro_opts_} ${shunit_constant_} +__shunit_constants=`set |grep '^__SHUNIT_' |cut -d= -f1` +echo "${__shunit_constants}" |grep '^Binary file' >/dev/null && \ + __shunit_constants=`set |grep -a '^__SHUNIT_' |cut -d= -f1` +for __shunit_const in ${__shunit_constants}; do + if [ -z "${ZSH_VERSION:-}" ]; then + readonly ${__shunit_const} + else + case ${ZSH_VERSION} in + [123].*) readonly ${__shunit_const} ;; + *) readonly -g ${__shunit_const} # declare readonly constants globally + esac + fi done -unset shunit_constant_ shunit_constants_ shunit_ro_opts_ +unset __shunit_const __shunit_constants + +# +# internal variables +# # variables __shunit_lineno='' # line number of executed test @@ -88,6 +104,9 @@ __shunit_assertsSkipped=0 # macros _SHUNIT_LINENO_='eval __shunit_lineno=""; if [ "${1:-}" = "--lineno" ]; then [ -n "$2" ] && __shunit_lineno="[$2] "; shift 2; fi' +#----------------------------------------------------------------------------- +# private functions + #----------------------------------------------------------------------------- # assert functions # @@ -313,8 +332,8 @@ _ASSERT_NOT_SAME_='eval assertNotSame --lineno "${LINENO:-}"' assertTrue() { ${_SHUNIT_LINENO_} - if [ $# -gt 2 ]; then - _shunit_error "assertTrue() takes one two arguments; $# given" + if [ $# -lt 1 -o $# -gt 2 ]; then + _shunit_error "assertTrue() takes one or two arguments; $# given" return ${SHUNIT_ERROR} fi _shunit_shouldSkip && return ${SHUNIT_TRUE} diff --git a/tests/test_cli.sh b/tests/test-cli.sh similarity index 100% rename from tests/test_cli.sh rename to tests/test-cli.sh diff --git a/tests/test_core.sh b/tests/test-core.sh similarity index 100% rename from tests/test_core.sh rename to tests/test-core.sh diff --git a/tests/test_util.sh b/tests/test-util.sh similarity index 100% rename from tests/test_util.sh rename to tests/test-util.sh diff --git a/tests/test_all.sh b/tests/unit-tests.sh similarity index 51% rename from tests/test_all.sh rename to tests/unit-tests.sh index 48f9262..acf1bba 100755 --- a/tests/test_all.sh +++ b/tests/unit-tests.sh @@ -1,5 +1,6 @@ +#!/bin/bash tests_succeded=true -for tst in $(ls $(dirname $0)/test_* | grep -v $(basename $0)) +for tst in $(ls $(dirname $0)/test* | grep -v $(basename $0)) do $tst || tests_succeded=false done