Skip to content

Latest commit

 

History

History
333 lines (243 loc) · 14.8 KB

README.md

File metadata and controls

333 lines (243 loc) · 14.8 KB

white-rabbit

A time recording tool

Build Quality Gate Status Coverage Maven Central

Screenshot of WhiteRabbit

Features

  • Records begin, end and interruption of your working day
  • Data storage in human readable json files, one file per month
    • Backup data by creating a git repository for the data folder and commit every day
  • Supported day types (see json example):
    • Normal working day (default for Monday to Friday): WORK
    • Weekend (Saturday and Sunday, detected automatically): WEEKEND
    • Public holiday (won't deduct overtime): HOLIDAY
    • Vacation (won't deduct overtime): VACATION
    • Flex time (will deduct overtime): FLEX_TIME
    • Sickness (won't deduct overtime): SICK
  • Automatic update in the background: just keep it running, and it will record your working time:
    • Start of work is detected when
      • Program start
      • Computer resumes from sleep in the morning
    • Detects the end of work when
      • Program shutdown
      • Computer sleeps for the rest of the day
      • You click the "Stop working for today" button
    • Interruptions detected when computer sleeps for more than 2 minutes
  • Generates reports for your vacation and monthly working time
  • Detects when a second instance is started to avoid data corruption
  • Export project working times to pm-smart. See below for details.

Java FX user interface

  • Double click on a table cell (Type, Begin, End, Interruption and Comment) to edit it
    • Interruptions must be entered as 01:23 for 1 hour, 23 minutes
  • Close the window to minimize in the task bar: white rabbit icon
    • Double click white rabbit icon to open the window again
    • Right click on white rabbit icon to add an interruption or exit the program

Notes

  • Won't work on weekends. To force working on a weekend, manually change the day type to WORK.
  • Public holidays can be calculated using plugin holidays-calculator or user can are set the day type to HOLIDAY manually.
  • If you manually change the working time in previous months you might need to adjust the overtimePreviousMonth field in the following months by selecting menu item File -> Update overtime for all months.
  • Assumptions:
    • Working time of 8h Monday to Friday
    • Mandatory break of 45 minutes after 6 hours of working

Usage

Requirements

Configuration

White Rabbit will search for the configuration file in the following locations:

  1. The path specified via command line parameter --config=<path>
  2. time.properties in the current working directory
  3. $HOME/.whiterabbit.properties

If the no config file is found, White Rabbit will create a default file at $HOME/.whiterabbit.properties, using data directory $HOME/whiterabbit-data.

The config file has the following content:

data = <path-to-data-dir> # e.g.: ../time-recording-data/

Restart WhiteRabbit after changing the configuration file.

Optional configuration settings

  • locale: format of date and time values as an IETF language tag, e.g. de, de-DE or en-GB. Default: system locale.
    • Note: enter a locale with country code (e.g. de-DE) to get correct formatting of date and time, e.g. the calendar week.
  • current_working_time_per_day: custom working time per day differing from the default of 8 hours. Format: see Duration.parse(), e.g. PT5H for 5 hours or PT5H30M for 5 hours and 30 minutes. This setting will only affect the future.

Project configuration

To use activity tracking, create file projects.json in your data directory with the following content:

{
    "projects": [
        {
            "projectId": "p1",
            "label": "Project 1",
            "costCarrier": "P1001"
        },
        {
            "projectId": "p2",
            "label": "Project 2",
            "costCarrier": "P1002"
        },
        {
            "projectId": "general",
            "label": "General",
            "costCarrier": "P0001"
        },
        {
            "projectId": "training",
            "label": "Training",
            "costCarrier": "P0002"
        }
    ]
}

Using Plugins

  1. Download one of the available plugins:
  2. Copy the downloaded plugin to $HOME/.whiterabbit/plugins/.
for plugin in pmsmart holidays-calculator csv demo
do
    fileName=$plugin-plugin-signed.jar
    curl https://whiterabbit.chp1.net/plugins/$fileName --output $HOME/.whiterabbit/plugins/$fileName
done

Logging

WhiteRabbit logs to stdout and to $data/logs/white-rabbit.log where $data is the data directory defined in the configuration.

Using pm-smart

Requirements for using pm-smart export
  • Microsoft Edge browser with password-less access to pm-smart
Setup and usage

  1. Create a project configuration as described above. Make sure to use the same IDs for costCarrier as in pm-smart.

  2. Make sure to install the latest version of the pmsmart plugin, see above for details.

  3. Add the base URL of your pm-smart server to the configuration file:

    pmsmart.baseurl = http://my-pmsmart.example.com

  4. In pm-smart open the week view ("Wochenansicht") and add favorites for all projects you use. The export will only work for projects added as favorite.

  5. Start the export in WhiteRabbit:

    1. Select the month that you want to export
    2. Select menu Reports > Project report
    3. Click button "Export to pmsmart"
Optional configuration settings

Optionally you can configure pmsmart plugin to skip transfer of a comment for each activity.

For each activity in WhiteRabbit you can enter a comment. By default pmsmart plugin transfers these comment to pm-smart. As the web ui is quite slow, transfer of comments can take a while. If you want to speed-up pm-smart export by skipping transfer of comments you can add an optional property to WhiteRabbit configuration file:

pmsmart.transfer.comments = false

Optionally you can configure pmsmart plugin to clear durations for all other projects, not matching any activity recorded in WhiteRabbit.

For each day pm-smart plugin by default transfers the durations of all activities entered into WhiteRabbit. If pm-smart contains durations for other projects then pm-smart plugin does not overwrite these. This will especially happen if users export their time recordings for a particular month multiple times and change the selection of activities in between. In order to ensure consistent data in pm-smart you can add an optional property to WhiteRabbit configuration file:

pmsmart.clear_other_projects = true

Using holidays-calculator

Optionally you can configure holidays-calculator plugin to enable WhiteRabbit to display your personal selection of holidays.

Setup and usage

Create a file named holidays.cfg in your data directory defined in the configuration file of WhiteRabbit.

You can use one of the predefined holiday definition files or you can edit the file and add or remove holidays to your own taste, see the holiday-calculator documentation for a detailed description of the syntax.

Note: WhiteRabbit adds holidays provided by plugins only to new months without any time recordings. As soon as the user adds a time recording for a particular month, WhiteRabbit saves the time recordings for this month including any holidays whether provided by plugins or entered manually. After this point in time for the given month WhiteRabbit uses only on the saved file and will not ask any plugin to update the holidays.

Development

Clone and configure

mkdir time-recording-data
git clone https://github.com/itsallcode/white-rabbit.git
cd white-rabbit
# Configure
echo "data = $HOME/time-recording-data/" > $HOME/.whiterabbit.properties

Using csv export

What can it do / limitations.

CSVExport plugin supports the export of the current monthly report to a pre-configured path. The file names are hard coded, and have the format of YYYY-MM_working_time.csv. Please note that all days must have a valid project assigned for the correct export.

Setup and usage

  1. Create a project configuration as described above.

  2. Make sure to install the latest version of the csv plugin, see above for details.

  3. Start the export in WhiteRabbit:

    1. Select the month that you want to export
    2. Select menu Reports > Project report
    3. Click the "Export to csv" button

Optional configuration settings

Currently, you can configure the destination path, separator and flag in WhiteRabbit's configuration file:

csv.destination = ~/working_time_reports
csv.separator = \t
csv.filter_for_weekdays = True

The default values are:

csv.destination = $HOME
csv.separator = ","
csv.filter_for_weekdays = False

Development

Clone and configure

mkdir time-recording-data
git clone https://github.com/itsallcode/white-rabbit.git
cd white-rabbit
# Configure
echo "data = $HOME/time-recording-data/" > $HOME/.whiterabbit.properties

Build and launch

# Build WhiteRabbit and install plugins to $HOME/.whiterabbit/plugins/
./gradlew build installPlugins
# To skip unit and ui-tests, run
./gradlew build installPlugins -x test -x uiTest
# Run
java -jar jfxui/build/libs/white-rabbit-fx-<version>[-SNAPSHOT].jar

# Build and run, loading plugins from $HOME/.whiterabbit/plugins/
./gradlew runJfxui

# Build and run including plugins. Useful when developing plugins.
# Make sure to remove unwanted plugins from $HOME/.whiterabbit/plugins/
./gradlew runJfxuiWithPlugins

Run UI-Tests

# Headless (default)
./gradlew check
# Not Headless (don't move mouse while running)
./gradlew check -PuiTestsHeadless=false

Check that dependencies are up-to-date

./gradlew dependencyUpdates

Deployment

This will build WhiteRabbit, upload it to the AWS S3 bucket and publish the plugin api to Maven Central.

Initial setup

  1. Setup of keystore and AWS configuration.

  2. Add the following to your ~/.gradle/gradle.properties:

    ossrhUsername=<your maven central username>
ossrhPassword=<your maven central passwort>

signing.keyId=<gpg key id (last 8 chars)>
signing.password=<gpg key password>
signing.secretKeyRingFile=<path to secret keyring file>
Build and deploy

  1. Make sure the Changelog is updated

  2. Run the following command:

    ./gradlew clean build publish closeAndReleaseRepository webstart:publishWebstart --info -PreleaseVersion=<version>

    The release will be written to jfxui/build/libs/white-rabbit-fx-<version>.jar and the uploaded content will be available at whiterabbit.chp1.net. Snapshots will be available at oss.sonatype.org.

  3. Create a new release in GitHub and attach the built jar.

  4. Close the milestone in GitHub.

  5. After some time the release will be available at Maven Central.

Managing WebStart configuration in a private branch

This project requires some configuration files with deployment specific information, e.g. domain names that should not be stored in a public git repository. That's why these files are added to .gitignore. If you want to still keep your configuration under version control you can do so in a private branch (e.g. private-master) that you push to a private repository only.

When switching from private-master to the public develop branch, git will delete the configuration files. To restore them you can run the following command in the project root:

git show private-master:webstart-infrastructure/config.ts > webstart-infrastructure/config.ts \
    && git show private-master:webstart/webstart.properties > webstart/webstart.properties \
    && git show private-master:webstart/keystore.jks > webstart/keystore.jks