Writing documentation is always a task which isn’t much liked and especially with diagrams and flowcharts there’s the problem of which tools to use. One crafty tool is Draw.io with web and desktop editors but what to use if you want to write documentation as a code and see the changes clearly in text format and maintain source-controlled diagrams? One of the tools for drawing diagrams with human readable text are mermaid and PlantUML.
mermaid
“Generation of diagrams and flowcharts from text in a similar manner as markdown.”
mermaid is a simple markdown-like script language for generating charts from text via javascript. You can try it in live editor.
mermaid sequence diagram
You can write mermaid diagrams in text editor but it’s better to use some editor with plugins to preview your work. Markdown Preview Enhanced for Atom and VS Code can render mermaid and PlantUML. There’s also dedicated preview plugins for VS Code and Atom.
To preview mermaid definition in VS Code with Markdown Preview Enhanced press Cmd-P to open Command palette and select Markdown Preview Enhanced: Open Preview.
mermaid in VS Code with Markdown Preview Enhanced
To preview mermaid definition in VS Code with Mermaid Preview press Cmd-P to open Command palette and select Preview Mermaid Diagram.
mermaid in VS Code with Mermaid preview
Generating PNG images from mermaid definitions
To use mermaid diagrams it’s useful to export them to PNGs. You can use mermaid.cli tool which takes a mermaid definition file as input and generates svg/png/pdf file as output.
If you have plenty of defition files you can use the following script to generate PNGs:
#!/usr/bin/env bash
for mmd in ./docs/*.mmd
do
filename="${mmd##*/}"
echo "Generating $mmd"
./node_modules/.bin/mmdc -i $mmd -o ${filename%%.*}.png
done
#!/usr/bin/env bash
for mmd in ./docs/*.mmd
do
filename="${mmd##*/}"
echo "Generating $mmd"
./node_modules/.bin/mmdc -i $mmd -o ${filename%%.*}.png
done
Alternatively you can use node_modules/mermaid/bin/mermaid.js $mmd where mmd is the mermaid file.
PlantUML diagrams
PlantUML is used to draw UML diagrams, using a simple and human readable text description.
PlantUML is used to draw UML diagrams, using a simple and human readable text description. Diagrams are defined using a simple and intuitive language (pdf) and images can be generated in PNG, in SVG or in LaTeX format.
You can use PlantUML to write e.g. sequence diagrams, usecase diagrams, class diagrams, component diagrams, state diagrams and deployment diagrams.
To preview PlantUML diagram in VS Code with Markdown Preview Enhanced press Cmd-P to open Command palette and select Markdown Preview Enhanced: Open Preview.
PlantUML in VS Code with Markdown Preview Enhanced
There’s an online demo server which you can use to view PlantUML diagrams. The whole diagram is compressed into the URL itself and diagram data is stored in PNG metadata, so you can fetch it even from a downloaded image. For example this link opens the PlantUML Server with a simple Authentication activity diagram.
Running PlantUML server locally
Although you can render PlantUML diagrams online it’s better for usability and security reasons to install a local server. And this approach is important if you plan to generate diagrams with sensitive information. The easiest path is to run PlantUML Server Docker container and configure localhost as server.
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
In VS Code config, open user setting, and configure like:
Now to preview diagram in VS Code press alt-D to start PlantUML preview.
PlantUML preview in VS Code and local server
You can also generate diagrams from the command line. First download PlantUML compiled Jar and run the following command which will look for @startXXX into file1, file2 and file3. For each diagram, a .png file will be created.
java -jar plantuml.jar file1 file2 file3
java -jar plantuml.jar file1 file2 file3
The plantuml.jar needs Graphviz for dot (graph description language) and on macOS you can install it from Homebrew: brew install graphviz.
For processing a whole directory, you can use the following command which will search for @startXXX and @endXXX in .c, .h, .cpp, .txt, .pu, .tex, .html, .htm or .java files of the given directories:
java -jar plantuml.jar "directory1" "directory2"
java -jar plantuml.jar "directory1" "directory2"
Maintain source-controlled diagrams as a code
Documentation and drawing diagrams can be simple and maintaining source-controlled diagrams with tools like PlantUML and mermaid is achievable. These tools are not like the behemoth of Sparx Enterprise Architect but provide light and easy way to draw different diagrams for software development. You don’t have to draw lines and position labels manually as they are magically added where they fit and you even get as crude boxes and squares as thousands of dollars more expensive tools. Now the question is which tool to choose: PlantUML or mermaid?
Web analytics is one the essential tools for a website and including measuring web traffic and getting information about the number of visitors it can be also used as a tool to assess and improve the effectiveness of a website. The most common way to collect data is to use on-site web analytics, measure a visitor’s behavior once on your website, with page tagging technology like on Google Analytics which is widely used web analytics service. But what would you use if you want to keep control over your own data?
You don’t have to look farther than Piwik which is open source web analytics application and aims to be the ultimate open alternative to Google Analytics. Here’s a short overview to Piwik Analytics and how to get started with it.
“Web analytics is the measurement, collection, analysis and reporting of web data for purposes of understanding and optimizing web usage.” – Wikipedia
Piwik Open Analytics Platform
Piwik is web analytics application which tracks online visits to one or more websites and displays reports on these visits for analysis. In short it aims to be the ultimate open source alternative to Google Analytics. The code is GPL v3 licensed and available in GitHub. In technical side Piwik is written in PHP, uses MySQL or MariaDB database and you can host it by yourself. And if you don’t want to setup or host Piwik yourself you can also get commercial services.
Piwik provides the usual features you would expect from a web analytics application. You get reports regarding the geographic location of visits, the source of visits, the technical capabilities of visitors, what the visitors did and the time of visits. Piwik also provides features for analysis of the data it accumulates such as saving notes to data, goals for actions, transitions for seeing how visitors navigate, overlaying analytics data on top of a website and displaying how metrics change over time. The easiest way to see what it has to offer is to check the Piwik online demo.
Feature highlights
You might ask how Piwik differs from other web analytics applications such as Google Analytics? One principle advantage of using Piwik is that you are in control. You can host Piwik on your own server and the data is tracked inside your MySQL or preferably MariaDB database: you’ve full control over your data. Software as a service analytics applications on the other hand, have full access to the data users collect. Data privacy is essential for public sector and enterprises who can’t or don’t want to share it for example with Google. You ensure that your visitors behavior on your website is not shared with advertising companies.
Other interesting feature is that it provides advanced privacy options: ability to anonymize IP addresses, purge tracking data regularly (but not report data), opt-out support and Do Not Track support. Your website visitors can decide if they want to be tracked.
You can also do scheduled reports which are sent by e-mail, import data from web server logs, use the API for accessing reports and administrative functions and Piwik also has mobile app to access the analytics data. Piwik is also customizable with plugins and you can integrate it with WordPress and other applications.
Piwik’s User Interface
Piwik has clean and simple user interface as seen in the following screenshots (taken from the online demo).
Piwik Dashboard
Piwik Visitors Overview
Setting up Piwik
Setting up Piwik is easy and there’s good documention available for running Piwik web analytics. All you need is web server like Nginx, PHP 7 and MariaDB which has in some cases significantly improved query performance and reliability of Piwik over using MySQL. You can setup it manually but the most easiest way to start with it is to use the provided Docker image and docker-compose. The docker-compose file setups four containers (MySQL, Piwik, Nginx and Cron) and with compose you can start it up. The Piwik image is available from official docker-library.
The alternative is to do your own Docker image for Piwik and related services. In my opinion it makes sense to have just two containers: one for Piwik related web stuff and other for MariaDB. The Piwik container runs Piwik, Nginx and Cron script with e.g. supervisor. The official image uses Debian (from PHP) but Piwik runs nicely also on Alpine Linux. One thing to tinker with when using Docker is to get MariaDB access to Piwik’s assets for LOAD DATA INFILE which will greatly speed Piwik’s archiving process.
If you’re setting up Piwik manually you can watch a video of installation and after that a video of configuring settings. After you’re done with the 5 minute installation you get the JavaScript tag which you add to the bottom of each page of your website. If you’re using React there’s Piwik analytics component for React Router. Piwik will then record the activity across your website within your database.
And that’s about all there is to starting with Piwik. Simple setup with Docker or doing it manually, adding the JavaScript tag, configuring some options if needed and then just wait for the data from visitors.
Summary
Piwik is good and feature rich alternative for web analytics application. Setting it up isn’t as straightforward as using some hosted service as Google Analytics but that’s the way self-hosted services always are. If you need web analytics and want to keep control of your own data and don’t mind hosting it yourself and paying for the server then Piwik is a good choice.
I’ve been using IRC for some time and although Irssi has served me well, it’s time to try something different. WeeChat is a modular chat client with support for IRC and the interesting part is that it’s possible to use other interfaces like glowing-bear web frontend. WeeChat is similar to Irssi so switching over shouldn’t be an issue. But to get the configuration right and what you had on Irssi needs some effort. Here are my notes about starting with WeeChat and how I like my chat client to look.
Compiling Weechat on CentOS 6
I have my shell on CentOS and although you can find WeeChat from the repositories, it’s quite old (0.4.3 when 1.4. is the newest). So you might want to compile WeeChat by yourself. Compiling WeeChat is explained on the User Guide. You need to install some libraries before you can try using make.
After you’ve installed the needed packages download WeeChat sources and extract the weechat-1.4.tar.gz package to directory you want.
Go to the directory you extracted WeeChat and run the following commands:
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/directory
$ make
$ make install
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/directory
$ make
$ make install
Configuring WeeChat
Quick Start guide helps you to get started so I don’t duplicate that here. If you’re familiar with Irssi you should feel more or less at home. As I didn’t use much scripts in Irssi the most difficult part for me was to create as good theme as I had with Irssi. Otherwise the switch went better than expected.
Start WeeChat with weechat so we can start configuration.
When I started with WeeChat of course I googled how others had configured it and thus my configuration is based on this and some other snippets.
buffer_autoclose.py: Automatically close inactive private message buffers.
iset.pl: Interactive Set for configuration options
colorize_nicks.py: Use the weechat nick colors in the chat area and command line.
urlbuf.py: Common buffer for received URLs.
irssi_awaylog.py: Log highlights/private messages when you are away.
screen_away.py: Set away status when detaching and attaching from screen or tmux.
To see and set the options for the plugins you can use /set with wildcard “*”
/set *urlbuf*
/set *away*
/set *urlbuf*
/set *away*
You can install scripts also by typing “script search iset” and a selection of available plugins will appear. To leave it type “q” then press enter, if you want to install the script type “i” then press enter.
Adjust layout and colors
Make the title bar and the status bar using dark colors.
Some visual bits to make Weechat a bit nicer. Like replace the nickname for a message with a little arrow if the previous message in your buffer was from the same user.
By default, WeeChat displays time and prefix for each line and optional bars around chat area which makes clicking long URLs impossible.
To make easier URL click, you have to options as explained in FAQ:
1. Enable option “eat_newline_glitch”, so that new line char is not added at the end of each line displayed (it will not break URL selection):
/set weechat.look.eat_newline_glitch on
/set weechat.look.eat_newline_glitch on
2. Move nicklist to top and remove alignment on nick:
/set weechat.bar.nicklist.position top
/set weechat.look.prefix_align none
/set weechat.look.align_end_of_lines time
/set weechat.bar.nicklist.position top
/set weechat.look.prefix_align none
/set weechat.look.align_end_of_lines time
I found the first option to be better as it lets you to have the prefix after nick and before text. It’s not as good as Irssi has it but it works. I hope they’ll merge this pull request which should make it better.
You can also use the bare display (default key: Alt+l).
Other notes
Joining channels with channel names on different character set, like ISO8859-1 and umlauts. You need to input the octal code for the letter, for example latin small letter a and o with diaeresis:
The default key is Ctrl+r (command is: /input search_text_here). And jump to highlights: Alt+p / Alt+n.
Log all messages on IRC buffers but not join/part/quit messages:
All IRC buffers: /set logger.level.irc 3
Server and its channels: /set logger.level.irc.freenode 3
Specific channel: /set logger.level.irc.freenode.#weechat 3
Configuration with iset
Now you should have basic setup quite right and to continue configurations it’s nice to use iset plugin. Just type /iset to enter the iset screen. You will now see a list of all the parameters which can be modified. If you type something in the input bar, it will look for the pattern in the list of variables. If you want to search through the values, put an = before the pattern.
To change the value, press Alt + Enter then enter the new value (it is possible to navigate through values depending on variable type by pressing the Tab key).
Summary
After short use WeeChat works as well as Irssi and vice versa. It will be seen if I stuck with it or get back to Irssi. I’m not quite satisfied with the configuration but it works well enough.
Vagrant is a great tool for creating and configuring lightweight, reproducible, portable virtual machine environments but the first step for using Vagrant, downloading an existing “base box”, raises some questions. E.g. How are these unverified boxes built? So, you might end up building your own base box which is often time consuming and cumbersome. Fortunately there’s a tool called Veewee which aims to automate all the steps for building base boxes and to collect best practices in a transparent way.
Vagrant Base Box with Veewee
Veewee is a tool for easily (and repeatedly) building custom Vagrant base boxes, KVMs, and virtual machine images. You can use it to build a Vagrant box in Linux, Mac OS X and Windows but I found out that fulfilling the requirements on Windows is quite difficult (read Ruby and RVM) so just forget it.
To get you started there are some requirements you need to fulfill. First you’ll need to install at least one of the supported virtual machine providers like VirtualBox and second you need some development libraries.
On Ubuntu 15.04 Linux and using VirtualBox you need these packages:
$ cd <path_to_workspace>
$ git clone https://github.com/jedi4ever/veewee.git
$ cd veewee
$ cd <path_to_workspace>
$ git clone https://github.com/jedi4ever/veewee.git
$ cd veewee
Set the local gemset and ruby version within the current directory:
$ rvm use ruby@veewee --create
$ rvm use ruby@veewee --create
Run bundle install to install Gemfile dependencies for your local gemset:
$ gem install bundler
$ bundle install
$ gem install bundler
$ bundle install
Bundle install will take some time.
Building Vagrant Box with Veewee
Veewee uses definitions to build new virtual machines and ‘definition’ is derived from a ‘template’ and preconfigured templates are found in templates/ folder. Veewee Basics explains how you can create your own customized definition.
For my customized Vagrant Box I decided to use Tommy Muehle’s definition as a template as it contained what I wanted. Simple CentOS 6.6. Box with Puppet. I just changed the localization to Finland and made it bigger for WebLogic use case in mind. My definition for Vagrant Box can be found in GitHub.
To use my definition just clone the repository for CentOS 6.6 Box, copy the “centos-6.6-x86_64_puppet” folder to definitions/ folder under Veewee and make your own changes if needed. After you’re done run:
The above command is actually calling “vagrant package –base ‘centos-6.6-x86_64_puppet’ –output ‘boxes/centos-6.6-x86_64_puppet'”. The machine gets shut down, exported and will be packed in a centos-6.6-x86_64_puppet.box file inside the current directory.
And you’re all done. Now you can use your just created base box for Vagrant boxes. Import it into Vagrant’s box repository and use it to initialize a fresh project:
Using Veewee to build a Vagrant Box is simple and what’s more important it’s automated and reproducible. Using Ruby and RVM on Windows 7 turned out to be practically impossible but old ThinkPad W510 with Ubuntu 15.04 worked nicely. Of course you could create a base box with Vagrant way which means installing and configuring your Linux manually. But why would you want to that if you can just automate it?
Doing things manually is fine once but if you can automate things it’s better. With little tools you can speed up development and reduce recursive mundane tasks such as starting a project or setting up boilerplate code. I recently came across Bower which is a package manager for the web. With Bower you can fetch and install packages from all over, and it takes care of finding, downloading, and saving the stuff you’re looking for. The other interesting tool to help you get going is Gulp which enables you to automate and enhance your workflow. Let’s see how to put things together on Windows, nothing special just steps to get you started.
Install Git
Bower needs Git to work so first install Git if you don’t have it. I chose Git for Windows which gives you BASH emulation used to run Git from the command line, graphical user interface for using Git and Shell integration.
Just click through the installation.
Install Node.js
Bower depends on Node.js and NPM so you need to get Node.js. Just download the installation package from Node.js site and click through it.
Install Bower
After you have Node.js installed we can install Bower with npm. You might need to restart your Windows to get all the path variables setup so Npm can find them.
Open up the Git Bash or Command Prompt and Bower is installed globally by running the following command.
$ npm install -g bower
$ npm install -g bower
Once you have Bower installed you then can install packages and dependencies using these commands:
# Using a local or remote package
bower install <package>
# Using a specific version of a package
bower install <package>#<version>
# Search packages
$ bower search <package>
# Using a local or remote package
bower install <package>
# Using a specific version of a package
bower install <package>#<version>
# Search packages
$ bower search <package>
By default packages will be put in the bower_components directory which can be changed if you prefer. If you want your packages downloaded into js/libs you can achieve this by creating a .bowerrc file
.bowerrc
{
"directory": "js/libs"
}
{
"directory": "js/libs"
}
You can also create a bower.json file which allows you to define the packages needed along with dependencies and then simply run bower install to download packages. In our example we setup a simple Backbone.js application which uses Bootstrap.
Our bower.json describes that we want some JavaScript libraries and as we have defined the version with ~ it can have bigger minor versions, e.g. jquery version can be between 2.0.3 < 2.1.0. Read more about semantic versioner for npm.
Now after creating that file inside the app directory you can run the following command:
$ bower install
$ bower install
After that you should see all your JavaScript packages under bower_components folder.
Install Gulp
To automate and enhance your workflow you can use Gulp for example to copy the files where you want them. There are nice recipes to show how to benefit of Gulp.
Install Gulp globally with npm:
$ npm install --global gulp
$ npm install --global gulp
Install Gulp also in your project devDependencies:
$ npm install --save-dev gulp
$ npm install --save-dev gulp
Now we can setup our Gulp dependencies which pull from npm. Create a new package.json file in your project root and just add an empty object, {} and save it.
Next we install gulp-bower plugin which we can use to install Bower packages.
$ npm install --save-dev gulp-bower
$ npm install --save-dev gulp-bower
This will install all the needed dependencies in a node_modules folder and also automatically update our package.json file with these dependencies.
Finally we need to setup the gulpfile.js which defines our tasks we want to perform. First we define what we installed in npm step above and create a config object to hold various settings. The bowerDir is just the path to the bower_components. Finally we add task for running bower and default task. Our bower tasks basically runs bower install but by including in the gulpfile other contributors only have to run gulp bower and have them all setup and ready.
The default task runs the bower task and all the user has to do to setup the needed packages is to run
$ gulp
$ gulp
In our case running gulp just runs our bower task which downloads the JavaScript packages we need. Pretty simple.
Gulp is powerful tool and has many use cases but also needs some to get all things working like you want and even then you might need to make compromises. One crafty task for Gulp and Bower is to customize your Bootstrap theme. Also Mark Goodyear has written good article about Getting started with gulp which shows some typical use cases.
Recently I switched from using Eclipse to IntelliJ IDEA as our Java EE application’s front-end was done with JavaScript and the support for front-end technologies in Eclipse is more or less non-existent. The switch for long time Eclipse user wasn’t easy as IDEA works a bit differently but the change was worth it. The biggest difference in daily work with IDE is the shortcuts which are quite different in IDEA. In theory you can use Eclipse keymap for shortcuts but it just doesn’t work like it should and in practice you have to learn the IDEA way. There are many posts in the Internet about keyboard shortcuts in IDEA but there’s always place for more :) So, here’s my list of shortcuts to keep in your finger memory.
Learn keymap with Key Promoter
To learn your way around IntelliJ IDEA’s keyboard shortcuts there’s nice “Key Promoter” plugin to train yourself. It prompts whenever you use the mouse when you could’ve used the keyboard instead (similar to Eclipse’s Mousefeed).
To install the plugin:
Ctrl+Alt+S to pull up the Settings screen
Filter on “plugin”. Click “Plugins”, then “Browse Repositories” at the bottom
Filter on “key promoter”
Double click to install
Essential IntelliJ IDEA keyboard shortcuts
You may be tempted to just go with the Eclipse keymap but it’s better to learn the IDEA way although it’s quite irritating at start. You also should change some default IDEA keyboard shortcuts to better ones like “closing editor window” with Ctrl+F4 which is too cumbersome compared to the de facto Ctrl+W. And changing “comment current line or selection” with Ctrl+/ which is impossible with Finnish keyboards to Ctrl+7.
Recent Viewed or edited Files: CTLR + E / CTRL + SHIFT + E
Shows you a popup with all the recent files that you have opened or actually changed in the IDE. If you start typing, you can filter the files.
Go to Class or file: CTRL + N and CTRL + Shift + N
Allows you to search by name for a Java file in your project. If you combine it with SHIFT, it searches any file. Adding ALT on top of that it searches for symbols. (Eclipse: Ctrl+Shift+T and Ctrl+Shift+R)
Find and Replace in Path: CTRL + SHIFT + F / CTRL + SHIFT + R
Allows you to find in files or replace in files. (Eclipse: Ctrl+H)
Incremental Find: F3 / CTRL + L
When using CTLR-F to find in current file the F3 lets you to loop through the results. (Eclipse: Ctrl+K)
Delete line: CTRL + Y
Delete current line under cursor. Yank it. (Eclipse: Ctrl+D)
Goto line: CTRL + G
Go to given line number. (Eclipse: Ctrl-L)
Syntax Aware Selection: CTRL + W
Allows you to select code with context. Awesome when you need to select large blocks or just specific parts of a piece of code.
Complete Statement: CTRL + SHIFT + ENTER
This will try to complete your current statement. How? By adding curly braces, or semicolon and line change.
Smart Type Completion: CTRL + SHIFT + SPACE
Like auto complete (CTRL + SPACE) but if you add a SHIFT you get the smart completion. This means that the IDE will try to match expected types that suit the current context and filter all the other options.
Reformat source code and optimize imports: CTRL + ALT + L
Allows you to reformat source code to meet the requirements of your code style. Lays out spacing, indents, keywords etc. Reformatting can apply to the selected text, entire file, or entire project.
Quick Fix: Alt+Enter
(Eclipse: Ctrl+1)
Gives you a list of intentions applicable to the code at the caret.
Paste one of the previous values from clipboard: CTRL + SHIFT + V
Shows you a dialog to select previous value from the clipboard to be pasted.
Comment or uncomment line or block: Ctrl+7 / Ctrl+Shift+7
Allows you to comment or uncomment the current line or selected block of source code. This is originally Ctrl + / (Slash) which is impossible with Finnish keyboard layouts.
Show Diff (in Changes): CTRL + D
In Changes tab compares the file with latest repository version.
Highlight Usages: CTRL + SHIFT + F7
Place the cursor in a element and after pressing the cursor the IDE will highlight all the occurrences of the selected element.
Go to Declaration: CTRL + B
If you place the cursor in a class, method or variable and use the shortcut you will immediately jump to the declaration of the element.
Refactoring String Fragments: CTRL + ALT + V
Refactor hardcoded string into variable/field/constant. Select the section of the String you want to extract, and use the normal “Extract…” shortcuts to extract it into a variable.
Other useful keyboard shortcuts
There are many useful keyboard shortcuts and you can print them from Help > Default Keymap Reference. Here are some more shortcuts which are also handy.
Update application: CTRL + F10
Current file structure: CTRL + F12
Bookmarks: F11 and SHIFT + F11
Generate Getters & Setters (in editor): ALT + INSERT
Create New _* (in project navigator): ALT + INSERT
Refactor – Rename: SHIFT + F6
Open Settings CTRL + Alt + S
Duplicate line: CTRL + D
Move line: CTRL + ALT + UP / DOWN
Find Command: CTRL + SHIFT + A
Show usages in a pop-up list: CTRL + Alt + F7
Extract Variable/Method/Constant/Field: CTRL + ALT + V/M/C/F
Quick JavaDoc Popup: CTRL + Q
Tab switcher: CTRL + TAB
Jump to Project Navigator: ALT + 1
Jump back to last tool window/panel: F12
Jump to beginning/end of block (e.g., method start/end): CTRL + [ and CTRL + ]
Toggle uppercase/lowercase of selection: CTRL + SHIFT + U
Toggle collapse/expand: CTRL + .
Toggle full screen editor (hide other tool windows): CTRL + SHIFT + F12
Not a keyboard shortcut exactly but the “iter” smart template is great. If you want to iterate though something using a for loop type “iter” then TAB to use the live template. It will figure out the most likely variable you want to iterate over and generate a for loop for it. In Eclipse it worked more logically with just typing for and then autocomplete.
Software development is fun if you have tools which work great and support what you’re doing. So it was finally great to get hear Sven Peters talking about better software development in teams as Atlassian’s Getting Git Right landed to Helsinki (24.11.2014). Event about Git and of course about Atlassian’s tools.
Getting Git right by svenpet and durdn
Getting Git Right’s main theme was about happy developers, productive teams and how Git and Atlassian’s tools help to achieve that. Sven Peters and Nicola Paolucci presented how to be a happier developer with Git, and how to ship software faster and smarter. It’s good to remember that developing software is after all a social challenge, not a technical one. And Git helps you with it. The presentation slides are available at SlideShare and you can also watch it on Youtube (different event).
Git: You can rewrite history. Timemachine without paradoxes
Nicola Paolucci gave a nice and 5 minute talk about Git and it’s internals. Lot’s of technical details. The main points were “Fast and compact”, “Freedom and safety”, “Explore and understand”, “Control and assemble”. With Git you can rewrite the history safely to e.g. clean commits. Paolucci showed also some tools to help working with Git on the command line like hooks they use and using “better” prompt like liquid-prompt. For GUI you can use Atlassian’s SourceTree.
Git datamodel
Merging
Interesting part of the event was talk about what is efficient and the best Git workflow? The answer is “we don’t know”. It depends as there are different cultures, different products and different teams. There’s no right way but there are some good workflows which might work for you.
One is to use branch per issue, e.g. hot-fix/jira-30-user-avatars, feature/jira-27-user-sign. The simplest workflow is to use feature branches with develop branch. Then the master is very stable. If you have multiple product versions then release branches are good and bug fixes are done to separate branch and merged to other branches.
They also presented how Atlassian’s Stash can help you to work with Git and branches. Like merging changes to branches can be done automatically with hooks or by using Stash. Stash looked nice for controlling and managing your repository with visual interface.
Code reviews: do they feel like this?
Git also helps you to improve code quality with e.g. code reviews. Code reviews shouldn’t be painful as it’s about team ownership, shared knowledge and aim for better code but often there’s developer guilt. It can be made easier by making code reviews part of your daily work by doing it in small patches like pull requests.
Development is also about communication and for that Atlassian presented HipChat. It looked quite nice tool for following what’s happening in a project with aggregating team chat and information from different tools. Following commits and continuous information brings you clear view what’s happening. There are also alternatives to HipChat like Slack or just basic IRC.
But why should you use Git? Benefits like more time to code, better collaboration, dev productivity and it’s the future doesn’t convince everyone. Like pointy haired bosses. So it’s good to remember that Git is also about economics. Delivering software faster, having less bugs and thus having happy customers. Shipping software faster and smarter.
Why Git? from Peters’ slides:
Why Git?
It’s also about economics
In Questions and Answers session there was talk about Atlassian’s strategy with Bitbucket and Stash. They said that both are going strong as they have different use cases. Stash has more enterprise features and you can have the repository on your own premises. Bitbucket is about hosting the repository in Atlassian’s platform and for small and medium team. What I have used Bitbucket it’s nice service but not as user friendly as GitHub. Another interesting question was about storing binary files in Git. There’s no optimal solution yet but just some workarounds like git-annex and git-media which allows managing files with git, without checking the file contents into git. In practice you shouldn’t store binary files in Git and you should separate product to code and assets.
Summary
Atlassians Getting Git Right was nice event and gave good overview about Git and how to use it in software development team. It would have been nice to hear something about the alternatives to Atlassian’s tools (BitBucket, Stash, SourceTree and HipChat) which helps you to do better software development. I can’t deny that Atlassian’s tools work nicely together but sometimes the price is just too high.
Now it’s time to start using Git also on work projects and as all participants got “Just do Git” T-shirt it’s easier :) Thanks to Atlassian and Ambientia for arranging this event.
The operating system running on Jolla has different and refreshing approach to user experience than the mainstream mobile operating systems. Sailfish OS is quite new project which also shows in applications’ user interfaces as common practices are not quite established. There are some guidelines and component usage examples how the applications should be built but they don’t cover every aspect especially with complex applications. Here are some examples how different apps solve common design issues in Sailfish OS.
Sailfish OS user interface design practices
Sailfish OS UI design practices
Sailfish OS guides you to make your app to work in certain ways and component gallery in development environment shows some practices but at the end how the app’s flow and user experience really works is up to the developer. There really isn’t comprehensive guide how elements and menu structures should work like there’s for Windows Phone and iOS. And thus Sailfish OS applications’ look and feel are sometimes quite different.
Here are some examples how different user interface aspects are designed in couple of Jolla’s own and third party developers’ apps. The presented examples and comments are just to point out different ways to build the user interface in Sailfish OS applications and doesn’t take a stance on which way is better or how it should be done.
Menu for different sections
There are couple of practices to present a menu for app’s different pages. The default is to use the pull down and push up menus but with more complex apps it’s not enough as the recommendation is to have only couple of items in that menu.
Tweetian (Twitter) uses bottom tab panel and you can flick left or right or press to change the page. In HalfTrail (map + GPS app) different sections are also as icons in bottom tab panel but activate only when pressed. In Haikala (high.fi news) settings page’s can be flicked or pressed with textual buttons.
Tab panel for pagesAction buttons on bottom panelBottom tab panel
Haikala uses side panel for actions to switch category. IRC uses the side panel for actions to select different IRC channels. Previously also Sailimgur (imgur) used left side panel for navigating to different pages.
Side panel for pagesSide panel for info & actionsSide panel for info & actions
Cargo Dock (file manager) is based on having two different sides and you can copy files between them. Both sides are identical but separate pages. Jolla Store shows links to apps in grid view and also arrows for selecting certain category of apps.
Two sides to work withArrows for sectionsGrid view for selecting items
Settings menu
Settings are usually shown in separate page like in Jolla’s Settings and Hunger Meter (battery usage). Terminal app on the other hand uses hamburger menu which opens side panel.
Settings pageSettings in own pageHamburger-menu settings
Showing controls and actions
Jolla’s Media app uses docked panel to show controls. The panel is shown only when a song is playing. You can also have docked panel with pull up menu for showing more controls icons. Tweetian has different actions in pull up and pull down menus.
Controls in docked panelDocked panel with pull up menuActions in Pull up menu
Other common way is to show controls in bottom or top panel with tool icons. This can be seen in HalfTrail with action buttons in bottom toolbar. In Paint there’s a top toolbar with icons. Neither provide legend for icons although Paint has help in About page. MitaKuuluu (WhatsApp) also uses bottom toolbar for chat related actions. In Sailimgur you can choose to have to toolbar at the bottom or at the top. The bottom toolbar has better reachability if used with one hand.
Action buttons on bottom panelTools in top panelActions in bottom toolbarToolbar at the bottomTop toolbar
Jolla Settings app uses switches to toggle different features. Terminal app on the contrary takes quite different approach to showing actions and settings. Terminal uses so called Hamburger menu which works quite nicely although isn’t “Sailfish OS” style.
Actions as switchesHamburger-menuHamburger-menu settings
Sailimgur shows actions for the photo when long pressed in a context menu. Actions related to a comment are shown as bottom context menu or icon buttons. Quickddit (Reddit) shows actions as icon buttons.
Actions in context menuActions in context menuActions as icon buttons
Back navigation
For the back navigation there isn’t a physical button and you either flick left, click page stack icon or use some button and action in pull down menu.
In Jolla’s Gallery app you scroll through photos in slideshow view and you get actions for back navigation only when pressing the photo and opening the Docked panel where you can flick back to the gallery overview. Alternative way for back navigation from photo slideshow is just press the photo as seen in e.g. Jolla Store.
Jolla Opas (Reittiopas) uses simple icon button in toolbar for navigating the route on the map and navigating back. And of course you can have the back navigation in pull down menu like in Sailimgur when navigating back from Web view.
Back navigation in docked panelBack navigation with buttonClosing view in pull down menu
Navigating between items
Navigating between items in a list is normally done by flicking left or right. But sometimes that’s not usable or it’s better to provide also alternative way.
Sailimgur has previous and next buttons at the bottom, Tidings (RSS feeds) provides them in pull down and pull up menus and Browser has them in bottom tool bar as icons.
Next & Previous as buttonsNext in pull down menuPrev/next in toolbar
Search
Providing search is usually done as a separate page but it can be put on pull down menu or as normal element in page.
Warehouse (OpenRepos) application has search link in pull down menu which navigates you to separate search page which also shows the results. Sailimgur has the search element in pull down menu and it closes after user presses enter to show the results in main view. Jolla Opas is a route planning app so the search elements are in main page. The search results are shown (if found more than one destination) as blue circle with results number and can be selected in separate dialog page.
Search in own pageSearch in menuSearch as main functionInline search in main view
Showing gallery of images
Showing list of images is pretty simple but there are differences how applications do it. Gallery application uses one big grid of cropped thumbnails, Warehouse shows full thumbnail and selection list in side and Jolla Store shows limited list of cropped thumbnails which opens in own view.
Only thumbnails, press to open own viewGrid view of imagesLarge image, side preview list
Notifications about new features
Mobile applications update quite often but users don’t usually check the changelog what’s changed or if there’s new features. So it’s nice to provide a simple changelog in first start like Flashlight, Paketti (post packages) and Haikala.
New features notificationShowing changelogChangelog dialog
Optical drives are nowadays less common on laptops which makes making bootable install medias a little easier. Yes, easier by requiring you to use USB thumb drives. There are different ways to achieve what you want and here is couple of examples how to transfer Linux install media to USB thumb drive on Windows and Mac OS X.
First you need to download the install media of your choice as ISO image which you want to transfer to your USB thumb drive. In theory you need a media which is meant for USB thumb drive or is a Hybrid ISO image but practically all modern distributions’ media are Hybrid ISO images.
Windows
Plug in the USB thumb drive and format it with FAT32 file system
Download UNetbootin and transfer ISO content to USB thumb drive using UNetbootin.
Select Diskimage and click the “. . .” button to find and open the ISO file. Make sure Type is USB drive and the Drive letter is what your Windows detect and click OK. Your ISO content will be copied to USB thumb drive.
Next you also need to copy the ISO file that you used with UNetbootin to the root of the USB thumb drive, e.g. the ISO file should be F:\linuxmint-16-cinnamon-dvd-64bit.iso
Now you can proceed to boot up the machine that you want to install with e.g. Linux Mint 16.
Linux
Creating bootable USB thumb drive in Linux is much simpler. You just need install media which is meant for USB thumb drive or is a Hybrid ISO image. With hybrid images, you can simply write the content of the ISO and make a bootable USB stick which can install Linux by using the ‘dd’ command.
You just need to have the ISO image and one command:
Where sdX is the device where your USB thumb drive is, e.g. sdb. If your system doesn’t support ‘oflag=direct’, you can just leave it out as it is simply intended to speed up the process a bit. If you leave the bs-option off the default will be 512 bytes and takes forever.
Mac OS X
OS X’s DiskUtil can’t burn ISO images to USB and gives “Invalid argument” but fortunately just like with Linux also Mac OS X makes things easy for you. You just need the install media which is meant for USB thumb drive or is a Hybrid ISO image. With hybrid images, you can simply write the content of the ISO and make a bootable USB stick which can install Linux by using the ‘dd’ command.
$ dd if=linux-image.iso of=/dev/rdiskX bs=8192
$ dd if=linux-image.iso of=/dev/rdiskX bs=8192
Where rdiskX is the device where your USB thumb drive is, e.g. rdisk1. You can see the device (disk identifier) from DiskUtility.app by selecting your USB stick and checking the Device section.
It’s useful to notice that on OS X you can use the ‘/dev/rdiskX’ device which stands for raw disk and is much faster than the block level device ‘/dev/diskX’ which is buffered and where data undergoes extra processing. For example rdiskX gives “823132160 bytes transferred in 625.470137 secs (1316022 bytes/sec)” and diskX gives “823132160 bytes transferred in 1296.675998 secs (634802 bytes/sec)”.
If you get an error e.g. “dd: /dev/rdisk2: Resource busy” then you have to make sure the Mac OS X isn’t using it and thus unmount it’s partitions. Open the DiskUtility.app, and on your USB hard drive, unmount any of it’s partitions. Do not eject the USB hard drive.
There are times when you have to do a clean install of your Windows 8 but if you have just an upgrade key you need to make couple of extra hoops before you can activate the new install. The upgrade key doesn’t prevent you installing to a clean disk but when you try to activate, you get an error 0x8007007B, saying your product key can only be used for upgrading. Another fine example how Microsoft makes things complicated for legitimate users.
Navigate to “HKEY_LOCAL_MACHINE/Software/Microsoft/Windows/CurrentVersion/Setup/OOBE/” and change the MediabootInstall key’s value from 1 to 0.
Open the Command Prompt (Win + R, type cmd). Right-click on the Command Prompt icon and run it as an administrator.
Type slmgr -rearm and press Enter.
Reboot Windows.
After that is done and you get back into Windows, you should be able to run the Activation utility and activate Windows as normal, without getting an error.
Apparently you can also call Microsoft Support and they will walk you through the proper way doing this because they understand you may have bought a new drive. There is a dialog you can get to in system tools where it will ask you for a numerical code. The support personnel will give you the number, you click “OK” after typing it in, then go the activation again and it works. This process is likely doing the work around mention above, but through an approved administrative process.
By the way, restarting Windows 8 is most easily done by left-clicking once on an empty spot on the desktop and holding Alt + F4).
