Contributing
The HMB project welcomes contributes of any skill set, you don't need to be a developer to get involved there is lots of work to do from writing documentations, filing bugs to help others to use HMB.
To engage with the Project you can raise an Issue or open a Discussion thread
Technology
Language
HMB is written in the Dart programming language using the Flutter framework.
This means that HMB runs just about everywhere (with some caveats), iOS, Android, Linux, Windows, MacOs and even web.
You can build HBM using any desktop OS - Linux, Windows or MacOs. I do most of my development on Linux but move to Windows when traveling.
Database
HBM use the sql3lite database with everything stored locally, the upside is that HMB will work even when you aren't connected. Each time the app is launched it will check if the database needs to be upgraded and automatically upgrade the database.
The upgrade scripts are shipped as assets in the assets/sql/upgrade_scripts
In development to upgrade the database create a .sql file with the name 'vNN.sql'
Where NN is the new version number. The version number must be an integer and should be one higher than the previous version file in the directory.
Once you have added a new version file you must register it by running the script:
tool/build.dart --assets
In development to upgrade the database create a .sql file with the name 'vNN.sql'
Where NN is the new version number. The version number must be an integer and should be one higher than the previous version file in the directory.
Once you have added a new version file you must register it by running the script:
tool/build.dart --assets
This script updates the asset/sql/upgrade_list.json file which is used at run time to identify the set of upgrade assets.
During development we try to keep the number of updates grouped into a single version. This is not a hard rule. Essentially during a chunk of dev just aggregate db updates into a single vNN.sql file until you are ready to push code. This may required you to keep deleting your database (the start up code reports its location). You can just do a 'rm ' and the app will recreate the db.
If another developer is actively working on the db version upgrades will need to be coordinated and this may require more frequent version number releases.
Building HMB
To build HMB:
Install Flutter
Install VS-Code (or an alternate IDE that supports Flutter).
forking the HBM repository on GitHub
clone the HMB repo to your local PC
check the hmb/tool directory for a platform specific setup script and if present run it.
You should now be ready to make changes to HMB.
Pre-release testing
Checklist of core items that need to be tested before each release:
Create Job
Create Customer
Create Contact
Create Site
Create Task
Create Checklist item
Create Time Entry
Stop stop task timer
Attach a photo
Tools
The project has a 'hmb/tool' directory you will find a number of scripts designed to help build the project.
tool/linux_setup.dart - run this if you are working on Linux
tool/build.dart - run this to build/deploy the project.
Database Upgrades
To modify the HBM schema create an sql file in hmb/assets/sql/upgrade_scripts. The file must be named v<nn>.sql where is the next number after the largest existing number.
The SQL must use sql3lite's SQL syntax.
Once you have added a new sql script to the above assets folder you need to run:
hmb\tool\build.dart -a
This will update the hmb/assets/sql/upgrade_scripts/upgrade_list.json to register your new script. The database upgrade will be applied next time you start HMB.
When we deploy a new version of HMB, starting HMB will upgrade the users version of their database. Depending on how long since the last update HMB, this may require multiple upgrade scripts to be applied which will be run in numerical order.
Deploying
Deployment is still a little under baked.
Android
You can install HMB to your Android phone by first placing it into Developer Mode Note: when in developer mode your google Wallet and other security apps may not function.
Plug your Android into you PC and respond yes when Android asked to grant permissions.
To build an install the apk to your Android phone run:
hbm/tool/build.dart
Project Icons
We use the dependency flutter_launcher_icons to generate the various icon sizes. To regenerate the icons run the following command:
flutter pub get flutter pub run flutter_launcher_icons:main
Linux
Provided you ran the hmb/tool/linux_setup.dart script when setting you development environment there should be nothing left to do.
You can launch the app from your dev environment or by running flutter run from the hmb directory.
If you are using vs-code here is a sample .vscode/launch.json script.
Web target
When running handyman in a browser, sqlite needs to have web support added to the package:
Instructions are here: https://github.com/tekartik/sqflite/tree/master/packages_web/sqflite_common_ffi_web#setup-binaries
As a convenience I've included the files it injects (the wasm binary) in the repo.
If we upgrade sqlflite we need to upgrade the injected files as per the above link.
Note: currently we are not backing up the db before doing schema upgrades as we don't know how to do this on the web.
If you want to use the Xero integration, when in debugging you need to launch the app with the args: --web-port 22433
see xero_auth.dart for details.
Xero
HMB supports xero for invoicing. This means that you can track your time in HMB (via creating time entries against a task) and then have HMB automatically generate an invoice in xero.
For this to work you need to:
Have an Xero account (the base one will do).
Log into the xero developer portal at: https://developer.xero.com/app/manage/
Within the developer portal: Add an App Configure a connection for the app; storing the client id and client secret into the system table - not currently not encrypted!
Add the following redirect URLs to the xero configuration:
For desktop (Windows and Linux):
For an android device:
Last updated