Toys warehouse and drones

Christmas is approaching and the elves are getting excited and stressed preparing all the packages. In 2024, North Pole is equipped with a Toy Warehouse that replaced the ancient Toy Workshop. Toys are now ordered to a network of third party elves workshops.

In the recent years, Santa simplified his deliveries by investing in a Reindeer Drones Delivery system, also known as RDD. It makes the work much easier and reduced deliveries errors: did you ever wonder why some persons were unhappy with their christmas present?

Toy Factory, by Steven Miller - CC BY 2.0 license

North Pole elves use top notch automation and deliveries dispatch systems, but still, this is a very critical time with a non-negotiable deadline. The stress is at its peak. All sort of operational issues must be managed, what requires to communicate efficiently with the DEBT (Devops Elves Backend Team).

Agile at the Toys warehouse

Santa's elves teams do daily standups. This is what Elf Product Owner decided after it looked like it would improve the overall North Pole teams' mental health. Each elf have to speak up and announce:

• what they did in the last day

• what they plan to do today

• announce any blocker so that other elves can support them

It proved to encourage team communication and Elf Product Owner is able to inform other teams about any blockers that could put this sensitive work at risk.

Someone is getting extra-stressed

Now Hermey the Elf got more problems... Since Hermey was not too interested in toys making and that he seemed to have an interest in meticulous work, Elf Product Owner decided to realocate him to the RDD team led by Elf Sparkle. Getting stressed about the long December month was already quite a burden. But speakink every morning in front of other elves about what he accomplished, tell his feelings, and asking for help is definitely too much for Hermey. The poor thing couldn't bear it and each day, he would babble a meaningless report. The stress of the social meeting makes it harder for Hermey because he is not the kind of person able to improvise a thirty-seconds talk.

App::Standup::Diary to the rescue

Sparkle, the team manager, noticed Hermey's struggle. She decided to share a tool she developed and used since a couple of years. "Take a look at App::Standup::Diary on the CPAN", she said. "It might help you organising your thoughts and communicate better.". Hermey nodded and went to his terminal:

    cpm install -g App::Standup::Diary

"Check the chat, I have sent you a nice bash alias" Sparkle said:

    alias diary="diary --data-dir ~/toy-warehouse/standup --project-name 'rdd'"

Once you will have configured that, we'll take a dive into the internals together!

Daily usage

--data-dir is where the stand-up notes are automatically stored and sorted by year and month. One file per day. --project-name is used for each note file name, as well as the file title. The directory tree looks like this:

tree /home/sparkle/toy-warehouse/standup
/home/sparkle/toy-warehouse/standup
├── 2021
├── 2022
├── 2023
└── 2024
    ├── 01
    ├── 02
    ├── 03
    ├── etc.
    └── 11
        ├── 2024-11-04_rdd.md
        ├── 2024-11-05_rdd.md
        ├── 2024-11-06_rdd.md
        ├── etc.
        ├── 2024-11-28_rdd.md
        ├── 2024-11-29_rdd.md
        └── 2024-11-30_rdd.md

This is all what you need to know to use it as your daily stand-up notes app. Just run diary every morning and get prepared for the next meeting. Maybe you want to know more about how it works, though?

A dive into App::Standup::Diary

Let's inspect what kind of marvels this command line tool contains. It use the following CPAN modules:

Object::Pad

It's used as a base OO toolkit for classes and roles. More on that later.

Time::Piece

Dates management.

Mojo::Template

Reusable boilerplate to generate stand-up Markdown files.

Path::Tiny

Directories and files path management.

The diary command-line tool retrieve the user arguments, create the diary file object and write it on disk.

GetOptions (
  "data-dir:s"      => \$data_dir,
  "project-name:s"  => \$project_name
) or die("Error in command line arguments\n" );

my $diary = App::Standup::Diary
  ->new(
    data_dir     => $data_dir,
    project_name => $project_name
  );

$diary->write;

The main App::Standup::Diary file compose two roles (with the :does() keyword) for dealing with the dates and project parts. Each role manage it's own set of fields, e.g. App::Standup::Role::Date provide the daily $date as a Time::Piece object so that it can be reused all over the place. The App::Standup::Diary::Template class generates Markdown files:

# <%= $project_name %> <%= $today %>

- done
- todo
- blocking

It doesn't allow customisation at the moment but we would really like to add a --template option so that the elves can provide a file type of their choice, or seasonnal ornaments for those who like ASCII art or emoji.

Usage of Object::Pad

App::Standup::Diary have been written with Object::Pad from scratch. It has not been converted from another OO toolkit, e.g. Moose. Its main class is equipped with the following fields:

• $daily_data_path

• $data_dir

• $template

In addition two more field are provided by the App::Standup::Role::Date and App::Standup::Role::Project roles:

• $date

• $project_name

It makes very easy to declare all the class fields at the top of the class. Various field attributes are available to manipulate each fields capacites:

field $daily_data_path :accessor;
field $data_dir        :param :reader;
field $template        :accessor :writer;

Note that field replaced the has keyword for attribute declaration in usual OO Perl toolkits. It's still possible to create non-class variables with e.g. my $santa, though, no worries. Now, let's take a look at the main method:

method write {

  $self->set_template( Standup::Diary::Template->new(
    date         => $self->date,
    project_name => $self->project_name
  ));

  if ( $self->should_create_dir ) {
    say "$daily_data_path should be created";
    $self->create_directories_tree;
  } else {
    $self->init_daily_data_path($self->build_path($self->date->ymd('/')));
  }

  my $file_path = path($self->build_full_file_path);

  path($file_path)->spew_utf8($template->render) and say "Diary entry created $file_path"
    unless $file_path->exists and say "Entry already exist";

}

The first benefit is that we have automatic method signature (if using Perl 5.26+), and that $self is provided without having to declare it. All class fields are available through $self, including the ones that comes from roles. Since $template got a :writer attribute, we got a set_template method to mutate it's value.

After testing the diary software for a couple of years, Sparkle consider writing new code for the Reindeer Drone Delivery core software with Object::Pad (or more likely it's core implementation) instead of the aging OO toolkits, as it prove to allow the writing of clearer code, with good separation of concerns and easily testable.

use Test2::V0;
use Time::Piece;
use App::Standup::Diary;

my $d = App::Standup::Diary->new( data_dir => 'north-pole-warehouse', project_name => 'rdd' );
isa_ok $d->date, 'Time::Piece';

$d->write;
ok -e $d->daily_data_path, 'The file have been created on disk';

my $today = localtime;
my ($year_month) = $today->ymd('/') =~ m/ \d{4} \/ \d{2} /gx;

is $d->daily_data_path, $d->data_dir . '/' . $year_month, 'Daily data path match today\'s date';

done_testing();

Happy advent season!

In the end Hermey finally got permission from Elf Product Owner to open a dentist's office at the North Pole, with having him scheduled for an immediate appointment after noticing something bad with his teeth. Sparkle improved the tool with the rest of the team, what made them more productive and relaxed.

Acknowledgments

The Santa's Helpers' Helpers article by D Ruth Holloway from the 11th day of the 2023 Advent Calendar was an inspiration to write this one.