Forem: John P. Rouillard

How does your customer help you?

John P. Rouillard — Thu, 14 Nov 2024 01:09:32 +0000

Many companies are cutting back and delaying new projects after the recent election. As a new solution provider, how do you create a win-win situation for customers who might worry about:

quality of the solution
satisfaction with the result
cost

How can you add value for the customer by reducing risk or cost?

I propose 4 types of customers:

Regular customer: straight work for hire.
Reference customer: provides a private reference for my work to a potential customer.
Sponsor customer: the company is publically promoted as a user of the product.
Partner customer: actively promotes the product within their market.

Regular customer

The customer receives a proposal for their project. Engages in discussions regarding the scope of work, pricing, and other details. Once the contract concludes, there is no continued relationship with the client.

Reference Customer

A reference customer starts as a regular customer. As part of the contract, they agree to talk with potential clients to discuss:

the project scope,
the benefits of the solution,
and the overall business impact of the work performed.

Contracts are protected by a non-disclosure agreement to safeguard the confidentiality of references. This allows prospective clients to better understand the value proposition. But it prohibits them from sharing any proposal-related information outside their organization.

In exchange for serving as a reference, these customers receive discounted rates on their contracts.

Sponsor Customer

A sponsor customer is a reference customer who has consented to publicly associate their company name with the solution/product. This association includes prominent visibility on websites, emails, and various marketing materials.

Sponsor customers receive a greater discount on their contracts compared to reference customers. They may enjoy other benefits, such as enhanced support agreements.

Partner Customer

A partner customer can be in any of the other customer categories. Unlike the other customers, who take a passive approach to supporting the product, these customers actively advocate for the product.

They share their positive experiences with others in the same industry. This strategy is particularly effective when the product offered is not a primary focus or distinguishing factor for the customer's business.

Rather than receiving discounts on contracts, these customers benefit from additional revenue when a client they refer decides to purchase the solution.

Conclusion

Offering customers an ongoing role in the success of your business can reduce their concerns about your solution. This win-win approach to negotiating contracts can also reach new clients and help answer the concerns of new clients.

What are your thoughts about these customer categories?
What tools/techniques do you use to help customers get
to yes?

(A good reference on negotiating is https://www.amazon.com/Getting-Yes-Negotiating-Agreement-Without/dp/0143118757.)

Copy issue reference to clipboard enhancement

John P. Rouillard — Thu, 09 Nov 2023 00:19:55 +0000

On the Roundup Issue Tracker mailing list a user asked for a mechanism to create a reference for the current issue and copy it to the clipboard.

The request was for the reference to look like:

  issue2345: title of issue

In Roundup, object designators like issue2345 are automatically hyperlinked to the corresponding object.

The code I recommended used a button to trigger this operation. It also used the clipboard API. When clicking on the button (or hitting space or return while focused on the button) the reference format above will be copied to the clipboard. Triggering the clipboard API must be done by a user interaction. For example: activating a button. If the browser does not support the clipboard API, a simple alert() is shown.

In addition to copying to the clipboard, the user gets feedback when the text of the button changes to "Reference copied". Then it resets to the original message after 2 seconds. Since clicking the button multiple times is idempotent, there is no sense in disabling or debouncing the button.

Note, this is unlikely to be a11y compliant as I don't think the change of button text is announced. If anybody has some ideas on how to make this more compliant, leave them in the comments. Maybe using aria-live="polite" or "assertive" on the button element would do the trick?

Here is the code I suggested:

<button id="copyreference" type="button"
            tal:condition="context/is_edit_ok">
   Copy Reference
</button>

<script tal:attributes="nonce request/client/client_nonce">
  (function () {
    "use strict";

    let crb = document.querySelector("#copyreference");
    if ( ! crb ) return
    crb.addEventListener("click", async (e) => {
        e.preventDefault()
        if ( ! navigator.clipboard ) {
            alert("Clipboard is not available")
            return
        }

        let issueDesignator = new URL(document.URL)
            .pathname
            .split("/")
            .pop()
        let issueTitleText = document.querySelector("#title").value;

        await navigator.clipboard.writeText(`${issueDesignator}: ${issueTitleText}`)

        let originalCrbInnerText = crb.innerText
        crb.innerText = "Reference copied"
        setTimeout(() => {
            crb.innerText = originalCrbInnerText}, 2000)
        }
    );
  })();

The flexibility of Roundup allows the administrator to rewrite all of the HTML used in the web interface. As a result, I based my guess of CSS selectors on the HTML generated by the classic issue.item.html TAL template.

The button could be placed anywhere on the page and the script (including the nonce required by the CSP) would be placed anywhere after the button. Probably at the end of the page so it doesn't block rendering.

The classic structure of the issue display page for users with editing capability included an input with the id title. This is retrieved using the id and included in the string written to the clipboard.

A user without editing capability for the issue (or without editing capability for the title attribute of an issue) does not have an input with id="title".
In these cases, the admin would have to modify the issue.item.html template to add an id of title to the enclosing element. Then the code above would be modified to replace:

let issueTitleText = document.querySelector("#title").value;

with:

 let issueTitle = document.querySelector("input#title");
   if ( ! issueTitle ) {
     issueTitle = document.querySelector("#title");
     issueTitleText = issueTitle.innerText
   } else {
     issueTitleText = issueTitle.value
   }

In my original example, the button element is generated only if the user can edit the issue. Removing the tal:condition attribute would always display the button.

There is nothing with an id or CSS selector that contains the object designator. I use the final element of the path of the URL to get the designator.

I chose to use the IIFE code structure. This allows me to use the early return pattern if the button is not found. If anybody knows how to do the equivalent of an early return without an IIFE or other function in a script tag, leave your trick in the comments.

If you use the Roundup Issue Tracker and have your own enhancements, feel free to mention them in the comments.

Roundup Issue Tracker - Roundup 2.4.0 documentation

A simple-to-use and -install issue-tracking system with command-line, web, REST, XML-RPC and e-mail interfaces. Adaptable to many use cases. Allows you to customize the look and feel and implement different workflows.

roundup-tracker.org

To Release or Not to Release: What's a Good Schedule

John P. Rouillard — Mon, 12 Jun 2023 17:15:00 +0000

Shakespeare once said "A rose by any other name would smell as sweet". I wonder if something similar can be said for software releases.

I am planning a new release of the opensource Roundup Issue Tracker. Historically, release schedules were on an as needed basis. Before 2006 (when version 1.0.0 was released) there were multiple years with more than 10 releases (including alpha/beta and other pre releases).

Year	Releases	Year	Releases
2022	2	2009	5
2021	2	2008	5
2020	2	2007	3
2019	2	2006	13
2018	1	2005	8
2016	1	2004	19
2013	1	2003	16
2012	2	2002	12
2011	3	2001	7
2010	5

But there were no releases from 2013 until 2016. Also, there was a gap in 2017. There was significant development done during those years without releases. But only those willing to run code from the repository were able to benefit. In 2018 I took over as release manager and chose to start doing yearly releases.

Why Release

With opensource projects, there are many reasons to release:

get features/bug fixes to users
thank contributors
increase project visibility
establish expectations
provide deadlines

As I mentioned above, producing a release makes the work of contributors (developers, documentation writers, people reporting issues) isn't generally available. Frequent releases align with my preference to reduce WIP (work in progress). Thanking the contributors by releasing their work helps drive enthusiasm and engagement.

Announcements on multiple platforms accompany each release. When I see another issue tracking/bug reporting program release announcement, I experience FOMO over the marketing provided by their announcement.

A regular release cadence helps users to schedule time for testing or upgrading the software. Also, regularly scheduled releases encourage developers to finish their work and get it into a release. This deadline also drives me to go through all the steps to generate a beta and final release. This year (2023) will be my 6th yearly release.

When to Release

Although I do believe that reducing WIP is important, Roundup is not provided as a SAS (software as a service). It is deployed on-prem and meant to be customized. Some changes to Roundup require changes to a customized installation as part of the upgrade. For example:

upgrade from Python 2 to Python 3 can require rewriting a tracker's business logic
support for newer databases versions can require table alteration (sometimes manual, sometimes programmatic using the roundup-admin migrate command)
security improvements and CSRF protection require changes to customized HTML templates.

I mentioned my FOMO when seeing other products release multiple times a year. I often see releases with 5 or so changes. Often these changes fix cosmetic issues or broken fields in the web interface.

With Roundup, many users have redesigned/replaced part of the interface. A release only supplies changes to the reference interfaces. The Roundup administrator needs to merge the reference changes into their production interface. In Roundup, changes can be implemented in production without requiring a release. This separation of concerns between the Roundup core and a customizable tracker makes Roundup more flexible. But, increases the work required during an upgrade.

Because of how customizable Roundup is, I try to balance between WIP and the churn caused by frequent releases. Yearly seems to be a sweet spot. There are occasions when a new core feature needs a change/bug fix. In that case the user has a choice to wait for a new release or use the most recent commit to the development repository.

If Roundup was a SAS with more limited customizability, we could do canary deploys directly from the repository. This would positively affect:

getting features/bug fixes to users
thank contributors

but would also reduce the utility of Roundup. Setting up a Getting Things Done tracker for his/her family would find it very difficult in a SAS based model. Also, the tempo of releases in a SAS based model may not align with the user's needs for a stable platform.

If Shakespeare were a software writer would he have penned "Would software by another release schedule smell as sweet?". Leave your thoughts in the comments.

(Cover Image by Glen Carrie)

Mobile Web Page Debugging Without a Desktop or USB Cable

John P. Rouillard — Sun, 19 Mar 2023 17:01:11 +0000

One of the things I have to do when developing a new tracker for the Roundup Issue Tracker is test on mobile browsers. When I run into issues, I used to hook up a remote debugger. This usually requires finding a USB cable as wifi is less reliable.

I really wish that mobile browsers had a native console that I could use to see console.log output and javascript errors. While not native, MobileConsole by hnldesign provides quite a bit of power by including one script and one style tag in my HTML page. At 45k uncompressed (17k gzipped) it's sized between the smallest and largest mobile consoles I found.

It can be seen at the bottom of the web page:

It supports the usual console output functions (error, ... debug). Plus it supports console.time/timeEnd and console.trace along with the group family. It also displays objects collapsed and allows you to toggle them open. The console can be resized allowing you to reduce the screen real-estate used on a mobile device.

It has some areas for improvement:

it only opens objects one level deep. So an array in an object is displayed but you can't expand the array further to get access to its elements.
grouping is not nested or collapsible. But this is noted as an area for improvement.

If you do a lot of logging, you might want to download the library, open your editor, and apply a change that reduces redraws triggered by console output.

One thing to note is that running commands in the console will not work if you are using a Content Security Policy (CSP). Any CSP that does not allow 'unsafe-eval' will prevent console commands from running. But at least you will see the error in the console 8-).

There are other mobile consoles as well:

mobileConsole is the smallest at 5k, but appears to only support console.log. Documentation is sparse and there is no demo.
B1naryStudio js-mobile-console - is 6k in size. It has methods to show/hide, enable auto-opening on error, and create command aliases. However, in its demo, I had issues with it displaying document.querySelect('body'). All it showed was an empty object {}.
Eruda is a console with a size of 130k gzipped. However, with that size, you get an element browser, network monitor, and other tools you know from your desktop browser's DevTools. It also has a plugin ecosystem. It properly handles console.group as a toggle. Also you can submit multi-line scripts. I think the only thing Eruda is missing is a debugger 8-).

Using hnldesign's MobileBrowser I was able to figure out why my javascript was crashing. If your hardware can handle it though, Eruda has many more features to make debugging on mobile device easier. Now the only time I need to find a USB cable is when I have to debug using breakpoints.

Do you have recommendations for other tools or techniques for debugging on mobile devices? If so leave them in the comments.

Can a Details Element be Used as an Accessible Popup (Without JavaScript)?

John P. Rouillard — Sun, 05 Mar 2023 17:30:00 +0000

I tried a little experiment to make a popup using a details element. The goal was to see if I could make a clickable popup without using JavaScript. It should be accessible for both sighted users and users using a screen reader like NVDA.

The HTML test case is a form with an info icon (the letter I in a circular blue field) after an input element. It is straightforward semantic HTML. The details element has a summary as its first element and a div enclosing paragraphs as the details' body. The summary element is the letter I styled using CSS to put the I (for info) on a circular lightblue field. The form looks like:

The HTML is:

  <body>
    <form>
      <div>
    <span><label for="a">A label:</label> <input id="a">
      <details class="inline" aria-live="polite">
        <summary aria-label="Activate for info on A label.">I<!--<img src="logo.png">--></summary>
        <div>
          <p>
        Here is a popup/popover with some interesting information
        about the <b>A label</b> input field. It might also be very
        boring. The choice is up to you. But I would make it
        interesting if I were you.
          </p>
          <p><em>Use space to close.</em></p>
        </div>
      </details>
    </span>
    <span><label for="b">B label:</label> <input id="b">
      </div>
      <div>
        <span><label for="c">C label:</label> <input id="c"></span>
...
  </form>
</body>

There is a small sprinkling of ARIA. The summary field's aria-label announces what happens when you open the details element. Originally I added aria-live="polite" on the div after the summary. But the detailed text was not announced when the details element opened. Moving aria-live to the details element, announced the text automatically when opened.

The summary icon trigger is opened by:

clicking on the icon with the mouse,
focusing on the icon (using tab) and
- hitting space or
- hitting return

Unlike other popups, this is triggered by a focusing user action rather than hover so it works on mobile as well.

The CSS was also rather straightforward. Changing the detail element's display to inline-block (default block) keeps it on the same line as the input. Changing the summary item's display to inline-block (default list-item) removes the open/close arrow associated with the details summary.

The icon was formed by using border-radius and background-color. To get things to align, I set the custom property --icon-size to the line height of the page. This property then gets used to square up (circle up 8-)) the shape of the summary text icon. You can use an image as well if you want. The background of the icon changes when opened, and can be seen through transparent parts of an image.

The details element (with the inline class) has its position set to relative. This makes positioning the div containing the detailed text easier. The div itself uses position: absolute. With these settings, the attributes left, top, right, and bottom can be used to shift the div relative to its default location.

This is the complete CSS:

/* styles for details popup */
:root { --icon-size: calc(1.5em); /* line height */ }
details.inline {
  display: inline-block;
  position: relative; /* anchor popup position */
}
details.inline summary {
  background-color: lightblue;
  border: 1px black solid;
  border-radius: 50%;
  cursor: default;
  display: inline-block;  /* remove marker */
  font-weight: bold;
  height: var(--icon-size); /* make icon round */
  text-align: center;
  width:var(--icon-size); /* make icon round */
}
details.inline summary img {
  /* if you want to use an image */
  height: var(--icon-size);
  width: var(--icon-size);
}
details.inline > div > * {
  margin-block: 0.25em;
  padding-inline: 0.25em;
}
details.inline[open] summary { background-color: yellow; }
details.inline[open] > div {
  background-color: white;
  border: 2px inset black;
  border-radius: 1em;
  left: -10ch; /* shift box to left */
  /* Move the popup box after the icon with
     a 5px gap */
  /* left: calc(var(--icon-size) + 5px); */
  position: absolute;
  /* To align first line of popup with the baseline of the icon:
   * shift up by 1/3 of the line height (--icon-size * -0.3333)
   * then shift down by the margin-block on the div (+ 0.25em).
   * This turns out to be 0.25em. */
  /*top: calc((var(--icon-size) * -0.333) + 0.25em);*/
  width: 40ch;
}

The open popup looks like this:

Prettier styling is an exercise for the reader 8-).

It can be enhanced with JavaScript to:

close with a keypress (using the escape key for example)
close with a mouse click outside of the popup
(see: details-utils)

Even without JavaScript, it is usable in Firefox and Chrome (which includes browsers like Edge, Brave, Vivaldi...). The details element should be accessible out of the box since it is a native HTML control. Although I only tested with NVDA and Windows Narrator, I expect it will work with other screen readers as well. (Note that Narrator would sometimes refuse to read the popup when opened. I have not discovered what causes it to refuse to read the popup on open. Moving the cursor with the right arrow key causes it to read the popup, and pressing the space key still closes the popup so....)

This seems to be a successful experiment. Custom variables, details element, and calc are all well supported. This technique should work on the majority of browsers out there today.

This technique will probably make it into some of the trackers I design for the Roundup Issue Tracker.

Leave your quips, comments, evasions, questions, or answers below.

Implementing a Command Palette and Task Timer (part 2)

John P. Rouillard — Sun, 19 Feb 2023 22:30:00 +0000

I am a developer for the open source Roundup Issue Tracker. It has many use cases. One is to develop issue trackers like GitHub Issues, Bugzilla, or Request Tracker. I also develop a custom issue tracker for a help desk environment. This article continues with the steps to add a task-timing feature for that tracker.

In part 1 of this series I had just finished installing command-pal. Let's take a closer look at command-pal before we get to the timer.

Enhancing command-pal and Handling a Showstopper

The Superhuman blog post lists other desirable features for a command palette:

fuzzy search (for mispelings 8-)) - is included in command-pal using fuse.js. (It looks like there is a fork of Ninja Keys that has fuzzy search support.)
icons - I created an issue and pull request to add support
synonyms - the fuzzy search includes the description field. This helps broaden the matching terms. But a description shouldn't be a keyword/synonym list. fuse.js can search an array of strings that are part of an object. Adding this functionality is a work in progress.

One interesting possibility is supporting multiple command palettes on a page. Each palette would have a different set of commands. I am not sure that's a good idea. Superhuman suggests making the command palette omnipotent. Multiple palettes force the user to make a decision about which palette to activate. This breaks the idea of "don't make me think". I was able to create and activate multiple palettes with different hotkeys. However, more work on supporting multiple palettes on a page is needed.

At its core, a command palette is a large select modal. Having the ability to activate the modal from Javascript could allow the palette to be used in more places without making the user think.

I am pleased with command-pal. I have found it quite hackable even though I have never used Svelte before. However, I did have one potential showstopper.

The tracker uses a Content Security Policy (CSP). Style blocks in the page include a nonce. If the nonce is missing or doesn't match the one in the CSP the style blocks are ignored. Svelte generates style blocks for each element that it creates/injects. These client-side blocks, don't have access to the server's CSP nonce. If they did have access to the nonce, the nonce would be useless for securing the page's assets. If the style blocks were in a file that could be fetched using a stylesheet link, everything would be fine. However, efforts to do this with Svelt have failed. Another alternative is to generate a secure hash (sha256, 384, or 512). How to get this generated at build time is unclear. However, I did find a way to calculate it at runtime that seems to work. I proposed a patch to allow an administrator to generate the hashes using the command-pal library.

The mechanism for controlling the task timer is done. Now to turn my attention to actually timing tasks.

Let's Time All The Things

I chose the easytimer.js library. It supports:

setting an initial value to start counting time
one minute timer granularity - to reduce CPU load
pausing and restarting timers while keeping their accumulated time.

The command palette allows the gross controls: stop/start/pause/resume. I still need to handle the other parts of the UI. The existing issue page provides a field for manually entering the task time. Rather than trying to create a new UI for the timer, I reused the existing field. The UI is relatively simple. There is a "Time spent" input element referred to as the "time element" below.

If the user prefills the time element with a number of minutes, the timer will start counting up from that time. This is helpful if you forgot to start the timer and start it after say 10 minutes.
The use case only requires 1 minute precision. Since I am counting in minutes, I add one minute to the start time. This rounds the time up to the next minute.
The time element is updated only once a minute. This is great for reducing CPU use, but poor for user feedback. There needs to be some way to notify the user that the timer is running. This needs to work without interfering with the ability to use the rest of the issue interface. Using a popup could work. But popups clutter the interface. If it can't be moved, it may hide something the user wants to use. Instead, I cycle the background color for the time element from yellow to goldenrod every 5 seconds. This is done using CSS rather than javascript. It should perform better than updating the input with a flashing indicator every second.
The animation stops when the timer is paused. But the yellow background color is still shown in the time element.
When the timer stops, the background of the time element returns to white.
Besides the time element displaying state, other elements of the page change as well. Starting the timer makes a pending change to the issue. The issue page already has a mechanism for indicating a page with a pending change. Starting the timer triggers this mechanism. This results in:
- a change in the background color of the time element label ("Time spent")
- a change in the background color for the H1 header on the page
- the H1 header on the page gets "pending changes" appended
- the title for the page has an exclamation mark prepended to it; allowing the page to be identified in a list of page titles
- the favicon for the page is overlayed with an exclamation mark inside a yellow dot; allowing the tab to be identified if the text can't be shown.

The command-pal Javascript Entries

Here are the three commands for working with the timer:

// more commands
{
  name: "Start or Unpause Timer",
  description: "timer",
  contexts: [ "issue.item" ],  // only show timers on an issue page
  handler: () => {
    if ( ! window.userTimer ) {
      try {
    // create the object
    window.userTimer = {
      timer: new easytimer.Timer({precision: "minutes"}),
      timeField: document.getElementById("time"),
      animation: null,
    }
      } catch (err) {
    alert(`Error: ${err.name} - ${err.message}`)
      }
    }

    let timer = window.userTimer.timer;
    let timeField = null;
    if ( window.userTimer.timeField ) {
      timeField = window.userTimer.timeField;
    } else {
      alert("Unable to find 'Time Spent' field. Are you viewing an issue?");
      return;
    }

    if ( timer.isRunning() ) {
      alert("Timer is running for: " + 
        timer.getTimeValues())
      return;
    }

    // restart timer
    if ( timer.isPaused() ) {
      timer.start();
      alert("Timer restarted at: " + 
        timer.getTimeValues())
      window.userTimer.animation.play()
      return;
    }

    // start timer instance
    let timeValue = parseInt(timeField.value);
    if (! timeValue || isNaN(timeValue)) { timeValue=0; }
    // round up time to next minute: 10 seconds -> 1 minute
    let startValues = { minutes: timeValue + 1 }

    timer.start({
      startValues: startValues,
      callback: function (timer) {
    let timeField = window.userTimer.timeField
    timeField.value = timer.getTotalTimeValues().minutes;
      }
    });
    alert("Timer started at: " +
      timer.getTimeValues())
    window.userTimer.animation = animate_timer(timeField);

    timeField.value = timer.getTotalTimeValues().minutes;

    // mark field/page with a pending change
    timeField.dispatchEvent(new Event('change',
                      {bubbles: true}))
  },
  icon: '<span class="icon">&nbsp;⏱️ </span>', // stopwatch emoji
  weight: 10, // sort this to the top of the list
},
{
  name: "Pause Timer",
  contexts: [ "issue.item" ],
  description: "Update time field and snooze the timer",
  handler: () => {
    if (! (window.userTimer && window.userTimer.timer) ) {
      alert("No timer was started.");
      return;
    }

    let timer = window.userTimer.timer
    let timeField = window.userTimer.timeField
    let animation = window.userTimer.animation

    if ( ! timer.isRunning() ) {
      alert("Timer is not running, time is: " +
        timer.getTimeValues());
      return;
    }
    timer.pause();
    animation.pause()

    timeField.value = timer.getTotalTimeValues().minutes;
    alert("Timer paused at: " +  timer.getTimeValues());
  },
},
{
  name: "Stop Timer",
  contexts: [ "issue.item" ],
  handler: () => {
    if (! (window.userTimer && window.userTimer.timer) ) {
      alert("No timer was started.");
      return;
    }

    let timer = window.userTimer.timer

    if ( ! ( timer.isRunning() || timer.isPaused() )) {
      alert("Timer is not running, time is: " +
        timer.getTimeValues());
      return;
    }

    let animation = window.userTimer.animation
    let timeField = window.userTimer.timeField

    timer.pause(); // stop time update
    timeField.value = timer.getTotalTimeValues().minutes;
    timer.stop(); // also zero's timer.
    animation.cancel();
    window.userTimer.animation = null;
  },
},
// more commands

(Note: the version of command-pal that I am running has the change to support icons.)

There is one helper function to set up the animation for the "Time spent" input field:

function animate_timer(input) {
  return input.animate(
    [
      {backgroundColor: 'yellow', easing: 'linear'},
      {backgroundColor: 'goldenrod', easing: 'linear'},
      {backgroundColor: 'yellow', easing: 'linear'}
    ],
    {duration: 5000, iterations: Infinity}
  );
}

Working Example

You can see this in action on the demo site. Use demo/demo for login. Activate the palette using ctrl+space. The code is also published.

Implementing a Command Palette and Task Timer (part 1)

John P. Rouillard — Sun, 05 Feb 2023 21:09:25 +0000

I am a developer for the open source Roundup Issue Tracker. It has many use cases. One is to develop issue trackers like GitHub Issues, Bugzilla, or Request Tracker. I also develop a custom issue tracker for a help desk environment. This article describes the steps in adding a task-timing feature for that tracker.

A user requested a task timer. The workflow:

open an issue page,
start a timer,
start the task associated with the issue,
use the issue page to document the work.

When done, the user would:

stop the timer,
finish documentation, attach files, and make other changes to the issue,
submit the time and other changes.

There are a few decisions to make:

timer functions
- is start/stop enough?
- is pause/restart needed?
- does the user need to change/set/edit the timer?
- do we need to track seconds, minutes, and hours? Since the customer is billed for the time, recording seconds seems excessive. Is there a scenario where the timer would need to record seconds?
timer controls
- do we use a button/buttons? Does checking a checkbox activate the timer?
- what does the UI look like for each timer function? Are the controls in the issue page? Are the controls in a floating popup? Does the popup need to be movable/collapsible so it doesn't block access to the underlying issue?
notification feedback
- how is the user notified that the timer is running/paused/stopped?
- how does the user see the elapsed time?
future planning
- how to add controls without cluttering an already complex interface
- what impact will this have on adding future feature requests in the same context
- does this guide us in implementing future workflows

Evaluating a Command Palette

I decided to try to install a command palette. A command palette is a UI interface usually activated by a hotkey. It allows searching and selecting from a context-sensitive list of commands. You might be familiar with the VS Code command palette. Command palettes have many advantages for users:

discover useful commands (and their shortcuts)
faster than scrolling down a long list of commands
keyboard is faster than using the mouse
invisible until activated
make commands available that wouldn't be important enough to get a button or other UI element

There are many command palette implementations in JavaScript. Some are used with specific frameworks. For example, kbar is a React component and spotlight is a Laravel component. I wanted one that would work with Vanilla JavaScript. I identified two candidates:

command-pal - "The hackable command palette for the web, inspired by Visual Studio Code."
Ninja Keys - "Keyboard shortcut interface for your website that works with Vanilla JS, Vue, and React."

Ninja Keys uses Lit while command-pal uses Svelte. I don't have any experience with either, so.... Both of them can bind any command on the palette to a hotkey thanks to hotkeys.js. Both are MIT licensed. Command-pal is larger in size, but it also bundles all the libraries it needs. It looks like Ninja Keys loads libraries/modules on demand from CDNs on the internet. Being able to use the library without internet access is a nice feature.

Command-pal promotes itself as "hackable". This usually means flexibility and sometimes simplicity. I like both. Command-pal's feature set wasn't as impressive as Ninja Keys. But it does include a floating button to trigger the command palette on mobile. This is a nice touch as moving the page to access UI elements can be tedious on mobile.

Adding command-pal

As a result, I chose command-pal. Integrating it was easy. I downloaded the file from the CDN. I also downloaded the dark theme from GitHub. I added a script tag and stylesheet link to the top-level page Roundup template file. This makes command-pal available on all the tracker's pages.

To invoke it, I added:

 const c = new CommandPal({
   hotkey: "ctrl+space",
   hotkeysGlobal: true,
   commands: commands,
 });
 c.start();

inside a script tag. The tracker is a web application. Sadly, the classic command palette hotkeys: "ctrl+k" or "ctrl+shift+p" are already used by the browser. I also wanted to activate the palette using the hotkey when focused on an input, select, or textarea. hotkeysGlobal: true should do that, but it didn't work for me in Firefox, Chrome, or Brave). I submitted a pull request to fix it.

The commands array included:

  [
    {
      name: "Exit Command Palette",
      contexts: [ "all" ],
      weight: -10,
    },
    {
      name: "Initial Screen",
      description: "Screen shown after login.",
      contexts: [ "all" ],
      handler: () => (window.location.href = "."),
      shortcut: "ctrl+i",_
      weight: 5,
    }, ...
]

Besides the fields used by command-pal:

name,
description,
handler,
shortcut

I added extra fields:

weight
contexts

These were inspired by the Superhuman blog on building a remarkable command palette. Among the things they suggest are:

order commands by popularity/utility
listed commands are context sensitive

The commands are initially sorted by weight (using commands.sort()). This displays the most popular (highest weight) commands at the top of the menu. Displaying the search results sorted by weight is an ongoing project.

The command is shown if its contexts property matches the current context. For example, the task timing commands only make sense when editing an issue. They should not be shown when viewing a list of issues, or a user's profile page. Inspecting the page's URL determines the current context. The code filters the command list, eliminating commands that are not appropriate for the context. Only then is CommandPal invoked.

I hope you have enjoyed learning about command palettes and command-pal in particular. In part 2, we will use command-pal to control the task timer and look at how it integrates with the tracker built using the Roundup Issue Tracker.

Roundup Issue Tracker - Roundup 2.4.0 documentation

roundup-tracker.org

A Modern Form Update and Interior Border Hack with CSS Grid

John P. Rouillard — Mon, 28 Nov 2022 17:01:41 +0000

I am a developer on the Roundup Issue Tracker. Roundup is a trouble ticketing system written in Python. It is very flexible. Developers, researchers, and support staff use Roundup to define and manage the lifecycle of issues.

My background is in system administration. So I have built a tracker template designed for tracking system administration issues. Recently I redesigned the look of one of the more complex forms.

This is the (short) story of the decisions I made and the techniques I used.

The starting point

I have limited design experience. When I set this up many years ago, it looked ok to me.

Looking at it today, the bold color swatches behind the fieldset legends and grooved borders make it seem cluttered and busy. It needs a more modern look.

Step 1 - fewer borders

First I removed the borders from the fieldsets. This brought up an issue. Tabbing through the form moves you down the columns (divs) and not across the rows. The borders and the gap between them helped re-enforce this.

I decided to add a vertical rule between the columns. I set border-inline-end to 2 pixels (2px) on the first column. When the first column was longer than the second this looked great. But, the fieldset panes in the first column are collapsible. When the first column was shorter than the second column, the line between the columns didn't reach the bottom of the second column.

The solution I came up with was to add a 2px border-inline-start on the second column. Then I moved the second column back by 2px (the width of the line) using margin-inline-start. These overlapped border lines always span the entire height of the longest column.

The layout uses the Gridiculous grid system rather than display: grid. This requires one last tweak. On narrower screens (e.g. a cell phone), the two side-by-side columns stack. Adding an @media query to remove the borders when on a narrow display completed the tweak.

How to make a vertical rule with css grid

I plan to use display: grid at some point for this layout. It would reduce the amount of CSS I need to serve and provide a more flexible layout. But, there is no mechanism for creating a rule in the gaps of a grid layout. I found a trick for doing that, but I haven't committed to using it yet. There is one nice advantage to using this trick. When the columns stack, grid removes the gap and also the (pseudo) vertical rule. No need for an @media cleanup.

To create the rule, I created a div (the base div) with the background-color set to the vertical rule's color. I set the CSS for that div to display: grid and the gap: 0 2px. I placed two divs inside the base div. They form the columns. Set their background-color to that of the rest of the page. Now the 2px column gap in the grid exposes the darker rule color of the base div. You can only emulate a solid border, but it works for my use case. Could linear gradients emulate a grooved, ridged, dotted, or dashed border?

My eyes, my eyes

The second change was to remove the banners of color behind the fieldset legends. With the more colorful themes, it's a bit bright on the eyes 8-). A simple underline matching the monochromatic theme replaces it. The HTML for the legend is <legend><span>Title Goes Here</span></legend>. Removing the background color from legend > span cleared the banner. Since the span is set to use display: block, adding a 2px border-block-end completed the work.

The final look

This is a significant improvement.

But it's still (a) bad form...

One question that you may ask is why tab order moves down the first/left column rather than across the form. As forms go this breaks a few rules:

use a single column for forms. In this case, I have not only two primary columns, but the basic fieldset has 2 subcolumns.
put labels above their control, or right-aligned labels to the left of the control (for ltr languages). Here, I use left-aligned labels to the left of the controls.

To justify my decisions, let's look at the use cases. As with most trackers, there are two types of users of this tracker. The:

people who need something done, and
the people doing the work.

There is also a third user, the person modifying the tracker for use at their site.

The left-hand column provides information for the people who need something done. Tabbing down the column moves the page like there was only one column. Ideally, these users would scan down the left column of the page. Using left-aligned labels provides this scan line.

Since Roundup can look at the user's role and remove/hide/collapse the second column we can get even closer to rule 1. This would make it a simpler form for these users. Still, displaying key status info above the fold requires packing a lot of fields in a small area. Following the "one column", "label on top" guidelines would increase scrolling.

There is one more tweak for this redesign. With the second column displayed, a skip link will be added at the bottom of the first column. The skip link will jump to the update textarea where the user can add a change note/update. This bypasses all the tab stops in the second column.

Adding a skip link at the top of the page to target the update textarea area is an idea. However, a skip link already exists at the top of the page. It jumps to the main section, bypassing the left-hand navigation column (not shown in the images). Would adding a second top-of-page skip link be confusing clutter? I'm not sure.

For people doing the work, references to the schedule and linked tickets are more useful. The second column provides access to them. The "All Fields" tab provides even more information hidden from view. For example:

summaries of related tickets
a graph of relationships among tickets
extra fields for scheduling automatic actions.

This brings us to the third user. I tried to set up a form that the Roundup admin could adapt for their workflows. The admin should not have to be an HTML/CSS expert. The idea of Roundup is that it is customizable for many use cases. I have tried to use clean semantic HTML and simple CSS to support that idea.

Thanks for reading this. I hope you enjoyed it and learned something. You can find more information on Roundup using the link below.

Roundup Issue Tracker - Roundup 2.2.0 documentation

A simple-to-use and -install issue-tracking system with command-line, web, REST, XML-RPC and e-mail interfaces. Adaptable to many uses cases. Allows you to customise the look and feel and implement different workflows.

roundup-tracker.org

My Journey to Open-Source Development

John P. Rouillard — Fri, 29 Jul 2022 05:49:19 +0000

Welcome to the first article on the ongoing development of the Roundup Issue Tracker. Before we get started, a little about me.

I have a B.S. in Physics which included some advanced computer science courses. But, my career ended up in system administration. I have taught and published a few peer-reviewed papers at conferences over the years. Trying to reduce toil and improve operations, lead to my interest in ticketing systems. Tools from LEAN and Six Sigma have proven valuable in analyzing ticketing and real-time logging data.

Issues Need Tracking

In 2002, I ran a lab that installed a system monitoring solution on Sun computers. We needed to track requests that came to the lab. I evaluated ticketing systems across a few dimensions. The Roundup Issue Tracker scored the highest.

Five minutes after downloading the software, I had a classic tracker running in demo mode. After entering a few tickets and adding a few keywords (tags), my co-worker and I decided it could work. It was flexible and looked like we could extend it to support our future growth. Little did I know that this was the start of a 20+ year relationship.

Roundup Basics

Roundup tracker has two components: the Roundup core and the tracker instance. The core is written in Python. The tracker instance supports one of two HTML templating engines: (Zope Page Templates or Jinja2). It is programmed in Python. The tracker instance controls the look/feel/functionality of the tracker. It:

defines the database schema/data model,
provides the web interface (with customizable HTML and CSS),
executes Python code to validate entered data and react to a change (e.g. by emailing notification messages),
can hook into the core code to control how the core operates.

One instance of the Roundup core can run many trackers. Each tracker can have a very different presentation and function.

Getting My Feet Wet

When I started, Roundup was still very new. I started developing my customized tracker to learn Python and experiment with Roundup. My tracker implemented several ideas from Request Tracker (RT). I developed the key components, replies/comments, dependencies, and grouping (parent/child), in less than 40 hours of effort over a few weeks. Roundup's implementation and documentation made building these significant features easy.

The other advantage was that Richard Jones, the developer, was in Australia. We set up a "follow the sun" development cycle. I emailed him a problem when I went to bed. By the time I got up the next morning, he would have a fix ready for me to use when I got home after work. This fast feedback is something I try to maintain in the Roundup community.

I never deployed my custom tracker, but the classic tracker worked well for the lab. As a result, the sales engineering group requested (and got) a tracker. After I left the company in 2005, they upgraded the Roundup core and converted the database to MySQL (from a dbm key/value store).

Back in a More Active Role

My next IT job used Request Tracker. I followed Roundup development but didn't contribute much. In 2012, there was some interest at work in setting up a customer-facing portal based on Roundup. I started development on my tracker again and re-joined the Roundup community. Over the next few years, I developed code to add:

a transaction source property for data changes. Makes changes from the web interface but prevents the same change if it originated from (unsigned) email.
the filter command to the roundup-admin command line interface makes data searching easier.
nofollow relationships to links which makes Roundup less useful to spammers.
CSRF protection using synchronizer tokens makes Roundup more secure.

Releasing Roundup

By 2018, Richard had stepped back, the last release was January 2016. I took over as a lead developer and release engineer. I released version 1.6.0 in July of 2018. This merged several existing patches, cleaning up Roundup's issue tracker.

Since 2018, there were two major changes added by other developers:

support for both Python 2 and Python 3 (which required a 2.0.0 release)
addition of a REST interface beside the XML-RPC interface

On July 13th, 2022, I made my fifth annual release.

Since Roundup deployments are on-prem, I established a yearly release cadence. Other issue trackers have more frequent releases. But, many of those releases address UI or workflow issues. In Roundup these are implemented in the (customized) tracker instance. So the user is not dependent on the fixes pushed from upstream. Each release includes upgrading instructions. These instructions can include changes for the tracker instance to bring it up to date.

The slower release cadence has an advantage for the users. It reduces the need to update tracker instances to once a year rather than every few months. However, the yearly cadence results in less public visibility for Roundup.

I plan more articles on developing and maintaining an open-source application. Some future topics I am considering include (in no particular order):

The Customisability Trap
Kitchen Sink Development
Accessibility
Responsive Design
The Problem with Selects
What?? No Javascript!
Docker All the Things
Colors and Themes
The Bus Factor
Evaluating Tracking Software

The Roundup 20^th anniversary article on lwn.net includes more information on Roundup.

I hope you enjoyed this article. Thanks for reading.

How to change details label when open/closed without JavaScript

John P. Rouillard — Mon, 12 Jul 2021 21:26:26 +0000

I wish the details element would support different labels (provided by the summary tag) for its open and closed states.

Consider a label of "Closed, click to open" when the details element is closed and "Open, click to close" when open:

Sadly only one summary tag is supported by the details element. However you can use an empty summary with a ::before pseudo-element to implement this.

Save the following to a file:



<html>
  <body>
  <style>
    #widget1 div { padding-inline-start: 1em; max-width: 20em;}
    #widget1 summary::before { content: "Closed, click to open";}
    #widget1[open] summary::before { content: "Open, click to close";}
    #widget1[open] summary { height: 2em;}
  </style>

  <p> Text before details.</p>
  <details id="widget1">
    <summary></summary>
    <div>
    A widget can be in one of two states. The default closed
    state displays only the triangle and the label inside summary
    (or a user agent-defined default string if no summary).
    </div>
  </details>
  <p>Text after details.</p>
  <body>
</html>

to experiment.
The second and third style lines are where the magic happens.

Note that it might not be accessible. I didn't try to see if adding a live region aria label to the summary would cause the label change to be announced. I suspect it will not, but refining this is left as an exercise for the reader. Add your experimental findings to the comments below.