Tag Archives: software

Version Control by the numbers

Posted on by

One of the least automated functions in software is the realm of numbering releases. Often, these numbers are functions of a marketing department, trying to impress customers rather than actually following any set standard.

In the movie Tron: Legacy, the character Alan Bradley, a former programmer, now executive, asks the president of ENCOM:

Given the prices we charge to students and schools, what sort of improvements have been made in Flynn... I mean, um, ENCOM OS-12?

And the president replies:

This year we put a "12" on the box.

Ironically, this is not as far from reality as you might expect. But suppose you are responsible for a software release. In that case, you need a version control numbering system that the engineering department can rely on, even if you need to maintain a translation grid somewhere else (hint: You probably will need one).

Version Number Basics

Numbering schemes vary by company but generally follow a template similar to this:

XX.YY.ZZ.AA

Where:

XX is a major release version number

YY is a minor release version number

ZZ is a patch release version number

AA (AAA) is the daily or latestrelease version number

The Daily or Latest release (AA or AAA)

The most automated of the version numbers is the daily or latest stable release number. If you use a build system, the last number is the build number. Every time code builds, the last number increments automatically, whether the build is successful or not. When the build is successful, usually by passing all automated tests, it is considered the latest stable build. This build is usually not released, but teams use it to develop additional features or patches or validate release candidates. While this build usually comes out of the development branch (in a three-branch system), nothing prevents it from coming from other automated build branches.

This number may or may not reset if one of the other three numbers is incremented based on the release management policy.

Many artifact repositories will alias the newest stable build as latest.

The Patch release (ZZ)

The most frequently updated public version number is the patch release number. This indicates changes to the base code that all users should take and update. This may include specific spot releases or roll-up patches from daily releases that are now regression tested and ready for everyone.

The patch release should not include new functionality. This release is a bug fix, major or minor, only.

The Feature Release (YY)

As an application matures, new features are added, and these features do not break backward compatibility but extend existing functionality or introduce new functionality. These releases tend to be less frequent than patch releases.

The Major Release (XX)

When an application does a major release, we discuss new features and functionality that break backward compatibility with prior versions. These big releases might include new kernels, schema designs, or APIs that no longer talk to older versions.

Major versions are often entirely new code bases, redesigned UIs, or tuned to specific hardware or changes to third-party requirements for API interactions. Depending on the software, it is usually possible to run two major versions simultaneously (although you probably do not want to).

Internal versus External Version Numbers

As mentioned, version control can be impacted by marketing. It is common, though bad practice, for the marketing version number not to be updated when a system is patched, even if the internal version number is updated. Sometimes this is to obscure the patch, sometimes, it is to prevent confusion with marketing campaigns and sometimes, it is contractual.

It is vital to ensure that regardless of the marketing number, you keep tight control of the internal numbers, incrementing them per build, patch or feature merge, and, finally, major releases. These numbers should result in tagging in the version control system, and all software that ends up in the artifact repository should be clearly identified.

Mermaid For Diagrams

Posted on by

A couple of months ago, I found a program called Mermaid, which is a javascript framework for translating markdown into process diagrams, and other relationships diagrams. This is a really cool thing.

Most of us, at some point in their career has been forced to create a process diagram of some kind. Or maybe its an Entity Relationship Diagram (ERD) or diagram a user journey. In many cases, if it is a simple diagram, you will open your PowerPoint analog program and hope you can make the boxes and arrows do what you want them to do. For more complicated diagrams, you probably opened a custom diagraming tool, like Lucid, or Miro, or Visio.

The largest problem with all of these tools is keeping the diagram current. The second problem is sharing the document. While many people think everyone runs Microsoft Office, the reality is that Office, and its analogs are falling behind the state of the art. Producing documents on tablets and phones need lighter weight applications, and what is lighter weight than raw text?

Markdown, properly parsed, can create elegant, multi-platform documents that can be managed in standard version control systems without a large amount of syntactic overhead associated with even the lightest weight outputs from applications like Word. Markdown supports PDFs, web pages, scripts, tables, and now, with Mermaid, complex diagrams!

Because of the various levels of support in browsers, and operating systems, there are many different ways to parse the data so everyone can see it. Let’s look at an example.

I took an existing process diagram that I created in Lucidchart and translated it into Markdown, and the code looks like this:

flowchart LR
    A[Rally Stories & Tasks] --> B[Developer Creates Code]
    B --> |GitHub Enterprise| C{Security Scan}
    C --> |Scan Fail| A 
    C --> |Scan Pass| D[Build Unit Artifact]
    D --> E{Automated Tests incl TDD-BDD-Smoke}
    E --> |Pass| G[Automatic Build of Materials]
    E --> |Fail| F[Teams Alert for SM]
    F --> A
    G --> H[Deployment to End-to-End]
    H --> I{Automated Tests incl TDD-BDD-Smoke}
    I --> |Pass| J[Artifactory-Promotable]
    I --> |Fail| F

Using the Mermaid Markdown parser (available from the Mac or iOS store), you get a simple diagram that looks like this:

But what is really nice, again, depending on your browser support, and underlying OS, if I embed the code above and wrap it in tags, you will get the embedded diagram (above) or you will get raw text, like the code block above (at least in WordPress). What is really nice, is if you check it into Github (change the wrappers), you have live diagrams, that are in version control and can be easily updated as the project or goals change. No more passing around files that cannot be edited, or can only be edited by one person. No more asking is this current. And that makes knowledge transfer easier.

Depending on your browser and OS, what is below is either the diagram, or the code.



flowchart LR
    A[Rally Stories & Tasks] --> B[Developer Creates Code]
    B --> |GitHub Enterprise| C{Security Scan}
    C --> |Scan Fail| A 
    C --> |Scan Pass| D[Build Unit Artifact]
    D --> E{Automated Tests incl TDD-BDD-Smoke}
    E --> |Pass| G[Automatic Build of Materials]
    E --> |Fail| F[Teams Alert for SM]
    F --> A
    G --> H[Deployment to End-to-End]
    H --> I{Automated Tests incl TDD-BDD-Smoke}
    I --> |Pass| J[Artifactory-Promotable]
    I --> |Fail| F

Installing MediaWiki on Ubuntu 18

Posted on by

A buddy sent a request. He was installing MediaWiki on Ubuntu and he was having issues so he asked me to take a look. I reviewed a link on Linux Support and HowtoForge on installing MediaWiki, and found them to be a tad dated. So, I went through the installation myself, and here is how I installed it.

All steps are done as an sudoer or as the root user. I did this on AWS with a Ubuntu 18.04 minimal base image. I assume you know how to log into a console. I used Apache. You can use Nginx, but the server directions are different and I did not have a chance to try them out.

Update the OS

sudo apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8
sudo add-apt-repository "deb [arch=amd64,arm64,ppc64el] http://mariadb.mirror.liquidtelecom.com/repo/10.4/ubuntu $(lsb_release -cs) main"
sudo apt-get update
sudo apt-get upgrade

Install basic packages

sudo apt-get install -y apache2 software-properties-common
sudo apt -y install mariadb-server mariadb-client
sudo apt install php libapache2-mod-php
sudo apt-get install imagemagick php7.2-fpm php7.2-intl php7.2-xml php7.2-curl php7.2-gd php7.2-mbstring php7.2-mysql php7.2-mysql php-apcu php7.2-zip

Once PHP is installed you will get a notice similar to:

NOTICE: Not enabling PHP 7.2 FPM by default.
NOTICE: To enable PHP 7.2 FPM in Apache2 do:
NOTICE: a2enmod proxy_fcgi setenvif
NOTICE: a2enconf php7.2-fpm

I enabled it after the fact and it worked. You can do it now or later as you desire.

Modify PHP settings (Optional)

If you are putting your server into production, use the following settings initially. If you are just looking around, the default php.ini settings are fine except for the timezone settings. You should set the timezone appropriately.

For production, edit /etc/php/7.2/apache2/php.ini and make the following changes:

memory_limit = 256M
upload_max_filesize = 100M
max_execution_time = 360
date.timezone = America/New York

Run the secure installation for MariaDB (Optional)

If you are running a production server, you should do a secure installation. 

sudo mysql_secure_installation

Create the MediaWiki table space

Login to MariaDB

mariadb -u root -p

And create the MediaWIki user and db as follows

CREATE DATABASE mediadb;
CREATE USER 'media'@'localhost' IDENTIFIED BY 'password';
GRANT ALL ON mediadb.* TO 'media'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

Where password is a secure password. This will be put into the MediaWiki configuration later, so do not forget it. The database mediadb and user media can be anything you want them to be.

Edit Apache’s site configuration

You will need to add MediaWiki to the site configuration. Create a new file called mediawiki.conf

sudo vi /etc/apache2/sites-available/mediawiki.conf

And add the following:

<VirtualHost *:80>
ServerAdmin admin@example.com
DocumentRoot /var/www/html/mediawiki/
ServerName example.com
<Directory /var/www/html/mediawiki/>
Options +FollowSymLinks
AllowOverride All
</Directory>
ErrorLog /var/log/apache2/media-error_log
CustomLog /var/log/apache2/media-access_log common
</VirtualHost>

Where the ServerAdmin variable should be real email address and the ServerName should be the domain name of the server. Also, ensure that the DocumentRoot is correct. If you only want to use MediaWiki, you can set the DocumentRoot to /var/www/html, but you have to modify a step below as well.

Restart everything

Do not restart the server yet! Instead, restart the key services. 

sudo a2ensite mediawiki.conf
sudo a2enmod rewrite
sudo systemctl start apache2
sudo systemctl enable apache2
sudo systemctl start mariadb
sudo systemctl enable mariadb

Download the current MediaWiki source

From the MediaWiki site, make sure you have the correct version. As of this writing, it is: mediawiki-1.33.1

Change to a temporary directory, download, untar, and move the file to the web server:

wget https://releases.wikimedia.org/mediawiki/1.33/mediawiki-1.33.1.tar.gz
tar zxvf mediawiki-1.33.1.tar.gz 
sudo mkdir -p /var/www/html/mediawiki
sudo mv mediawiki*/* /var/www/html/mediawiki

If you modified the DocumentRoot in the Apache configuration to /var/www/html, you will need to modify the command above. You will only need to move the contents of the base mediawiki folder:

sudo mv mediawiki*/* /var/www/html

Point your browser at the web site

Depending on your confirmation you can either use localhost or the hostname of your server. If you use the mediawiki folder option, you have to put the folder on the end. 

http://<hostname>/mediawiki

Good luck!

Web Links

MAX and Human Errors

Posted on by

What Really Brought Down the Boeing 737 Max? - The New York Times

In the drama of the 737 Max, it was the decisions made by four of those pilots, more than the failure of a single obscure component, that led to 346 deaths and the worldwide grounding of the entire fleet.

I am not a pilot, and I have never been at the controls of an airplane. This very long article does go into a number of issues surrounding a complicated piece of technology. Take a read. It does not take any responsibility off of Boeing, but it certainly does not make them out to be the only villain in the story.

Using A New Tool

Posted on by

Every now and then, I find a new tool to make my life easier, at least that is the theory. My first new tool was to ditch Microsoft Windows for the MacOS. At least as my primary day-to-day OS. Yes, I spend a large portion of my work day in Linux. At the moment the distribution is Ubuntu, but I spend most of my day staring at a terminal emulator. When I am not doing that, the OS should be something I do not have to think about, and Windows, especially Windows 8, was causing me too much thought. Then with the release of Windows 10 and all the things that are talking back to Microsoft, I decided it was time to try something else. So Mac won, despite the costs.

As many of you know, I have a certain loathing for the Mac. My primary arguement has (and still is) cost. It is just too bloody expensive. It has the advantage of being Unix like under the covers though, and it has a couple of other advantages in terms of photo work that Windows, even with all the RAM I could throw at it, just could not measure up to. So, I bit the bullet and went Mac.

With the conversion, came a couple of new tools, of which this is one - it is a piece of blogging software call Byword, and is a combination text editor, markdown support. It seamlessly connects with my blogging platform (which is good) and supports markdown which is good because more and more of my documents are being written in markdown than they are in anything else. It is more portable and just a better way of doing things. This is the first post with the Byword, and I am doing it more to test out the software than anything else. So here we go.

Hello world!