Merge pull request #79 from topkecleon/develop

Sync Developer notes and Tools to master

README.md

@@ -20,11 +20,13 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
 1. Go to the directory you want to install bashbot, e.g.
     * your $HOME directory (install and run with your user-ID)
     * /usr/local if you want to run as service
-2. Clone the repository:
+2. [Download latest release](https://github.com/topkecleon/telegram-bot-bash/releases)  archive from github and extract all files. 
+
+    As an alternative you can clone the github repository to get the latest, but possible unstable improvements.
     ```
-    git clone --recursive https://github.com/topkecleon/telegram-bot-bash
+    git clone https://github.com/topkecleon/telegram-bot-bash
     ```
-3. Change to directory ```telegram-bot-bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather.
+3. Go to directory ```telegram-bot-bash```, run ```./bashbot.sh init``` and follow the instructions. At this point you are asked for your Bots token given by botfather.
 
 ## Update bashbot
 1. [Download latest update zip from github](https://github.com/topkecleon/telegram-bot-bash/releases)
@@ -52,6 +54,7 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
     * Seperate logic from commands
     * Test your Bot with shellcheck
 * [Bashbot function reference](doc/6_reference.md)
+* [Notes for bashbot developers](doc/7_develop.md)
 
 ## Note on Keyboards
 From Version 0.60 on keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed.
@@ -99,4 +102,4 @@ Bashbot is not more (in)secure as any other Bot written in any other language, w
 
 If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-0-g3b17bc2

README.txt

@@ -17,8 +17,8 @@ Prerequisites
 Depends on http://github.com/tmux/tmux[tmux]. Uses
 http://github.com/dominictarr/JSON.sh[JSON.sh].
 
-For full UTF-8 support you need
-link:doc/4_expert.md#UTF-8-Support[python on your system] (optional).
+Most complete link:doc/4_expert.md#Bashbot-UTF-8-Support[UTF-8 support
+for bashbot] is availible if phyton is installed (optional).
 
 Bashbot https://github.com/topkecleon/telegram-bot-bash[Documentation]
 and https://github.com/topkecleon/telegram-bot-bash/releases[Downloads]
@@ -30,13 +30,17 @@ Install bashbot
 1.  Go to the directory you want to install bashbot, e.g.
 * your $HOME directory (install and run with your user-ID)
 * /usr/local if you want to run as service
-2.  Clone the repository:
+2.  https://github.com/topkecleon/telegram-bot-bash/releases[Download
+latest release] archive from github and extract all files.
++
+As an alternative you can clone the github repository to get the latest,
+but possible unstable improvements.
 +
 ....
-git clone --recursive https://github.com/topkecleon/telegram-bot-bash
+git clone https://github.com/topkecleon/telegram-bot-bash
 ....
-3.  Change to directory `telegram-bot-bash`, run `./bashbot.sh init` and
-follow the instructions. At this stage you are asked for your Bots token
+3.  Go to directory `telegram-bot-bash`, run `./bashbot.sh init` and
+follow the instructions. At this point you are asked for your Bots token
 given by botfather.
 
 Update bashbot
@@ -71,6 +75,7 @@ Documentation
 ** Seperate logic from commands
 ** Test your Bot with shellcheck
 * link:doc/6_reference.md[Bashbot function reference]
+* link:doc/7_develop.md[Notes for bashbot developers]
 
 Note on Keyboards
 ~~~~~~~~~~~~~~~~~
@@ -161,5 +166,5 @@ That's it!
 If you feel that there's something missing or if you found a bug, feel
 free to submit a pull request!
 
-latexmath:[\[VERSION\]] v0.60-0-gf5162e2
+latexmath:[\[VERSION\]] v0.61-0-g3b17bc2
 ++++++++++++++++++++++++++++++++++++++++

bashbot.rc

@@ -1,7 +1,7 @@
 #!/bin/sh
 # description: Start or stop telegram-bash-bot
 #
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-0-g3b17bc2
 # shellcheck disable=SC2009
 # shellcheck disable=SC2181
 

bashbot.sh

@@ -10,7 +10,7 @@
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 #
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-0-g3b17bc2
 #
 # Exit Codes:
 # - 0 sucess (hopefully)

commands.sh

@@ -4,7 +4,7 @@
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 #
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-0-g3b17bc2
 #
 # shellcheck disable=SC2154
 # shellcheck disable=SC2034
@@ -100,7 +100,7 @@ else
 		'/question')
 			checkproc 
 			if [ "$res" -gt 0 ] ; then
-				startproc "./question"
+				startproc "example/question"
 			else
 				send_normal_message "${CHAT[ID]}" "$MESSAGE already running ..."
 			fi
@@ -109,7 +109,7 @@ else
 		'/run-notify') 
 			myback="notify"; checkback "$myback"
 			if [ "$res" -gt 0 ] ; then
-				background "./notify 60" "$myback" # notify every 60 seconds
+				background "example/notify 60" "$myback" # notify every 60 seconds
 			else
 				send_normal_message "${CHAT[ID]}" "Background command $myback already running ..."
 			fi

dev/hooks/pre-commit.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+#### $$VERSION$$ v0.61-2-gfd4dd8c
+
+# magic to ensure that we're always inside the root of our application,
+# no matter from which directory we'll run script
+GIT_DIR=$(git rev-parse --git-dir)
+cd "$GIT_DIR/.." || exit 1
+
+export HOOKDIR="dev/hooks"
+
+echo "Running pre-commit hook"
+
+# if any command inside script returns error, exit and return that error 
+set -e
+
+# let's fake failing test for now 
+echo "Running tests"
+echo "............................" 
+
+unset IFS; set -f
+
+# check for shellcheck
+if which shellcheck >/dev/null 2>&1; then
+	echo "Test all scripts with shellcheck ..."
+else
+	echo "Error: shellcheck is not installed. Install shellcheck or delete $0"
+	exit 1
+fi
+
+# run shellcheck before commit
+echo "read files from dev/shellcheck.files ..."
+FILES=$(sed '/^#/d' <"dev/shellcheck.files")
+if [ "$FILES" != "" ]; then
+	# shellcheck disable=SC2086
+	shellcheck -x ${FILES} || exit 1
+	echo "OK"
+else
+	# something went wrong
+	exit 1
+fi

dev/hooks/pre-push.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#### $$VERSION$$ v0.61-2-gfd4dd8c
+
+# magic to ensure that we're always inside the root of our application,
+# no matter from which directory we'll run script
+GIT_DIR=$(git rev-parse --git-dir)
+cd "$GIT_DIR/.." || exit 1
+
+export HOOKDIR="dev/hooks"
+
+REMOTEVER="$(git ls-remote -t --refs 2>/dev/null | tail -1 | sed 's/.*\/v//')"
+VERSION="$(git describe --tags | sed -e 's/-.*//' -e 's/v//')"
+
+echo "Running pre-push hook"
+
+# if any command inside script returns error, exit and return that error 
+set -e
+
+# let's fake failing test for now 
+echo "Running tests"
+echo "............................" 
+
+unset IFS; set -f
+
+# LOCAL version must greater than latest REMOTE release version
+if (( $(echo "${VERSION} > ${REMOTEVER}" | bc -l) )); then
+	# update version in bashbot files on push
+	dev/version.sh 2>/dev/null
+else
+	echo "Error: local version ${VERSION} must be greater than latest release version."
+        echo "use \"git tag ...\" to create a local version greater than ${REMOTEVER}"
+	exit 1
+fi
+

dev/install-hooks.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# this has to run once atfer git clone
+# and every time we create new hooks
+#### $$VERSION$$ v0.61-2-gfd4dd8c
+
+# magic to ensure that we're always inside the root of our application,
+# no matter from which directory we'll run script
+GIT_DIR=$(git rev-parse --git-dir)
+cd "$GIT_DIR/.." || exit 1
+
+HOOKDIR="dev/hooks"
+
+echo -n "Installing hooks..."
+for hook in pre-commit pre-push
+do
+   rm -f "${GIT_DIR}/hooks/${hook}"
+   if [ -f "${HOOKDIR}/${hook}.sh" ]; then
+	echo -n " $hook"
+	ln -s "../../${HOOKDIR}/${hook}.sh" "${GIT_DIR}/hooks/${hook}"
+   fi
+done
+echo " Done!"

dev/shellcheck.files

@@ -0,0 +1,15 @@
+# list of files to run shellscheck against
+#### $$VERSION$$ v0.61-2-gfd4dd8c
+# main files
+bashbot.sh
+commands.sh
+bashbot.rc
+# example files
+examples/calc.sh
+examples/notify.sh
+examples/question.sh
+# dev files
+dev/version.sh
+dev/install-hooks.sh
+dev/hooks/pre-commit.sh
+dev/hooks/pre-push.sh

dev/version.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 #
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 # shellcheck disable=SC2016
 #
 # Easy Versioning in git:
@@ -34,24 +34,29 @@
 # run this script to (re)place Version number in files
 #
 
+# magic to ensure that we're always inside the root of our application,
+# no matter from which directory we'll run script
+GIT_DIR=$(git rev-parse --git-dir)
+cd "$GIT_DIR/.." || exit 1
+
 unset IFS
 # set -f # if you are paranoid use set -f to disable globbing
 
 VERSION="$(git describe --tags --long)"
-echo "Update files to version $VERSION ..."
+echo "Update to version $VERSION ..."
 
-FILES="* doc/*"
+FILES="* doc/* dev/* dev/*/*"
 [ "$1" != "" ] && FILES="$*"
 
 for file in $FILES
 do
 	[ ! -f "$file" ] && continue
 	#[ "$file" == "version" ] && continue
-	echo -n " $file"
+	echo -n " $file" >&2
 	sed -i 's/^#### $$VERSION$$.*/#### \$\$VERSION\$\$ '"$VERSION"'/' "$file"
 done
 # try to compile README.txt
-echo -n " README.txt"
+echo -n " README.txt" >&2
 pandoc -f markdown -t asciidoc  README.md | sed '/^\[\[/d' >README.txt
 echo " done."
 

doc/1_firstbot.md

@@ -61,5 +61,5 @@ group. This step is up to you actually.
 
 #### [Next Getting started](2_usage.md)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 

doc/2_usage.md

@@ -159,5 +159,5 @@ send_action "${CHAT[ID]}" "action"
 #### [Prev Create Bot](1_firstbot.md)
 #### [Next Advanced Usage](3_advanced.md)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 

doc/3_advanced.md

@@ -58,7 +58,7 @@ you have to use the function ```user_is_allowed``` to check if a user has the ca
 ```
 
 ### Interactive Chats
-To create interactive chats, write (or edit the question script) a normal bash (or C or python) script, chmod +x it and then change the argument of the startproc function to match the command you usually use to start the script.
+To create interactive chats, write (or edit the exmaples/question.sh script) a normal bash (or C or python) script, chmod +x it and then change the argument of the startproc function to match the command you usually use to start the script.
 The text that the script will output will be sent in real time to the user, and all user input will be sent to the script (as long as it's running or until the user kills it with /cancel).
 To open up a keyboard in an interactive script, print out the keyboard layout in the following way:
 ```bash
@@ -90,9 +90,9 @@ Note: Interactive Chats run independent from main bot and continue running until
 
 ### Background Jobs
 
-A background job is similar to an interactive chat, but runs in the background and does only output massages instead of processing input from the user. In contrast to interactive chats it's possible to run multiple background jobs. To create a background job write a script or edit the notify script and use the funtion ```background``` to start it:
+A background job is similar to an interactive chat, but runs in the background and does only output massages instead of processing input from the user. In contrast to interactive chats it's possible to run multiple background jobs. To create a background job write a script or edit the examples/notify.sh script and use the funtion ```background``` to start it:
 ```bash
-background "./notify" "jobname"
+background "examples/notify.sh" "jobname"
 ```
 All output of the script will be sent to the user or chat. To stop a background job use:
 ```bash
@@ -156,5 +156,5 @@ answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
 #### [Prev Advanced Usage](3_advanced.md)
 #### [Next Expert Use](4_expert.md)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 

doc/4_expert.md

@@ -96,13 +96,13 @@ To change back the environment to your user-ID run ```sudo ./bashbot.sh init```
 To use bashbot as a system servive include a working ```bashbot.rc``` in your init system (systemd, /etc/init.d).
 
 ### Scedule bashbot from Cron
-An example crontab is provided in ```bashbot.cron```.
+An example crontab is provided in ```examples/bashbot.cron```.
 
 - If you are running bashbot with your user-ID, copy the examples lines to your crontab and remove username ```nobody```.
-- if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
+- if you run bashbot as an other user or a system service edit ```examples/bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
 
 #### [Prev Expert Use](4_expert.md)
 #### [Next Best Practice](5_practice.md)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 

doc/5_practice.md

@@ -89,9 +89,9 @@ Line 17:
 ```
 As you can see my ```mybotcommands.inc.sh``` contains an useless echo command in 'TEXT=' assigment and can be replaced by ```TEXT="${TEXT}${WORD}"```
 ```bash
-$ shellcheck -x notify
+$ shellcheck -x examples/notify
 OK
-$ shellcheck -x question
+$ shellcheck -x examples/question
 OK
 $ shellcheck -x commands.sh
 OK
@@ -112,5 +112,5 @@ The second warning is about an unused variable, this is true because in our exam
 #### [Prev Best Practice](5_practice.md)
 #### [Next Functions Reference](6_reference.md)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 

doc/6_reference.md

@@ -216,11 +216,11 @@ fi
 ##### startproc
 ```startproc``` starts a script (or C or python program etc.) running in parallel to your Bot. The text that the script outputs is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats)
 
-*usage:* startproc "./script"
+*usage:* startproc "script"
 
 *example:* 
 ```bash
-startproc './calc'
+startproc 'examples/calc.sh'
 ```
 
 ##### checkproc
@@ -232,7 +232,7 @@ Return true (0) if an interactive script active in the given chat.
 ```bash
 checkproc 
 if [ "$res" -gt 0 ] ; then
-  startproc "./calc"
+  startproc "examples/calc.sh"
 else
    send_normal_message "${CHAT[ID]}" "Calc already running ..."
 fi
@@ -258,11 +258,11 @@ fi
 
 In contrast to interactive chats, background jobs do not recieve user input and can run forever. In addition you can suspend and restart running jobs, e.g. after reboot.
 
-*usage:* background "./script" "jobname"
+*usage:* background "script" "jobname"
 
 *example:* 
 ```bash
-background "./notify" "notify"
+background "examples/notify.sh" "notify"
 ```
 
 ##### checkback
@@ -275,7 +275,7 @@ Return true (0) if an background job is active in the given chat.
 checkback "notify"
 if [ "$res" -gt 0 ] ; then
   send_normal_message "${CHAT[ID]}" "Start notify"
-  background "./notify" "notify"
+  background "examples/notify.sh" "notify"
 else
  send_normal_message "${CHAT[ID]}" "Process notify already running."
 fi
@@ -346,6 +346,7 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca
 Send Input from Telegram to waiting Interactive Chat.
 
 #### [Prev Best Practice](5_practice.md)
+#### [Next Developer Rules](7_develop.md)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ v0.61-2-gfd4dd8c
 

doc/7_develop.md

@@ -0,0 +1,37 @@
+#### [Home](../README.md)
+## Notes for bashbot developers
+This section is about help and best pratices for new bashbot developers. The main focus on is creating new versions of bashbot, not on develop your individual bot. Nevertheless the rules and tools described here can also help you with your bot development.
+
+bashbot development is done on github. If you want to provide fixes or new features [fork bashbot on githup](https://help.github.com/en/articles/fork-a-repo) and provide changes as [pull request on github](https://help.github.com/en/articles/creating-a-pull-request).
+
+### Setup your develop environment
+
+1. install git, install [shellcheck](5_practice.md#Test-your-Bot-with-shellcheck)
+2. setup your [environment for UTF-8](4_expert.md#Setting-up-your-Environment)
+3. clone your bashbot fork to a new directory ```git clone https://github.com/<YOURNAME>/telegram-bot-bash.git```, replace ```<YOURNAME>``` with your username on github
+4. create and change to your develop branch ```git checkout -b <YOURBRANCH>```, replace ```<YOURBRANCH>``` with the name you want to name it, e.g. 'develop'
+5. give your (dev) fork a new version tag: ```git tag vx.xx```, version must be higher than current version
+6. setup github hooks by running ```dev/install-hooks.sh``` (optional)
+
+### Versioning
+
+Bashbot is tagged with version numbers. If you start a new development cycle you must tag your fork with a version higher than the current version.
+E.g. if you fork 'v0.60' the next develop version should tagged as ```git tag "v0.61-dev"``` for fixes or ```git tag "v0.70-dev"``` for new features.
+
+To get the current version name of your develepment fork run ```git describe --tags```. The output looks like ```v0.70-dev-6-g3fb7796``` where your version tag is followed by the number of commits since you tag your branch and followed by the latest commit hash. see also [comments in version.sh](../dev/version.sh)
+
+To update the Version Number in your scripts run ```dev/version.sh```, it will update the line '#### $$VERSION$$ ###' in all files to the current version name.
+
+If you actived git hooks in Setup step 6, 'version.sh' updates the version name on every push
+
+### Shellchecking
+
+For a shell script running as a service it's important to be paranoid about quoting, globbing and other common problems. So it's a must to run shellchek on all shell scripts before you commit a change. this is automated by a git hook activated in Setup step 6.
+
+In addition you can run ```dev/hooks/pre-commit.sh``` every time you want to shellcheck all files given in 'dev/shellcheck.files'.
+
+
+#### [Prev Function Reference](6_function.md)
+
+#### $$VERSION$$ v0.61-2-gfd4dd8c
+

examples/bashbot.cron

@@ -7,7 +7,7 @@
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 #
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ 0.70-dev-4-g12fd839
 
 
 SHELL=/bin/sh

examples/calc.sh

@@ -3,7 +3,7 @@
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ 0.70-dev-4-g12fd839
 
 # adjust your language setting here
 # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

examples/notify.sh

@@ -2,7 +2,7 @@
 
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ 0.70-dev-4-g12fd839
 
 # adjust your language setting here
 # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

examples/question,sh

@@ -3,7 +3,7 @@
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 
-#### $$VERSION$$ v0.60-0-gf5162e2
+#### $$VERSION$$ 0.70-dev-4-g12fd839
 
 # adjust your language setting here
 # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment