Software Meadows

Navidrome IIS Reverse Proxy

Fri, 2 Jan 2026 09:24:48 -0700

This is a quick post, not a full How To.

BLUF
To use IIS as your reverse proxy for Navidrome: a) enable WebSockets, and b) clear the Accept-Encoding header's value

I recently replaced my long-running (and woefully unmaintained) Subsonic self-hosted music server with Navidrome. This was initially (relatively) painless, as Navidrome has:

A native Windows installer that also installs a Windows Service
Straightforward ability to point to my existing library
Reasonably easy to import playlists I exported from Subsonic

There were a few barriers.

The documentation didn't seem as clear as I'd have liked on how configuration options work. Specifically, that options can be set in the navidrome.ini file OR server environment variables, and that the option names are not the same. But, in fairness, this was probably me being impatient.
Navidrome organizes songs completely based on tags. This makes sense, but initially showed lots of my albums as separate songs. It was tedious (but worthwhile) to tag those songs to include Album Artist. The tagging guidelines documentation is very useful here . . .
- Except, that in some cases the Year tag is what would cause albums to show separately. I'm pretty sure this has more to do with a bunch of MP4 (.m4a) files I have. Someday I'd like to convert those to MP3 and then reget the album info.
My previous Subsonice reverse proxy didn't work with Navidrome.

The last one is the subject of this post. I lost about eight hours on it. The reason to use a reverse proxy is because the Navidrome application (web server) doesn't support SSL. But, if using the app publically (not just within one's local network), SSL (HTTPS) is essential for security. Most of the web examples of using a reverse proxy with Navidrome use nginx. I came very close to installing and using nginx, but that would have required me switching all of my other sites to use it to. Ugh.

I use Microsoft Internet Information Server (IIS) on purpose; I'm a Microsoft stack developer, and need to understand the tools. And it seemed like it should work. But I kept getting an HTTP 500 error.

Finally, after looking at logs and beating my head against the keyboard (didn't help), I installed Fiddler Classic to watch the traffic. It didn't tell me more than I knew, but then I tried sending my GET request from Fiddler.

And it worked.

Fiddler Compose, by default, only uses two headers. This led to a process of elimination of the headers being sent. Fiddler made this pretty easy since I could copy the headers I sent from my browser request (examinging Fiddler Inspection) directly into the Fiddler Compose, eliminating them until it worked again. It turned out, the Navidrome app's web server doesn't accept encoding (or at least not standard encoding).

Once I knew that, I could update IIS Url Rewrite to include the server variables (not at all well documented how those relate to HTTP headers) and change their values.

Sorry, you'll need to do your own research on configuring IIS as a reverse proxy. There may be a better way than what I've done (because I'm still finding different documentation on how to do it).

Here's the web.config I used. It:

Passes requests from https://music.flattland.com to Navidrome
Changes the Accept-Encoding request header via a server variable
Allows (somehow) WebSockets passthrough
Rewrites outbound URL tag values if the Navidrome URL http://localhost:4533 is found

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="ReverseProxyInboundRule1" stopProcessing="true">
                    <match url="(.*)" />
                    <action type="Rewrite" url="http://localhost:4533/{R:1}" />
                    <serverVariables>
                        <set name="HTTP_SEC_WEBSOCKET_EXTENSIONS" value="" />
                        <set name="HTTP_ACCEPT_ENCODING" value="" />
                        <set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="{HTTP_ACCEPT_ENCODING}" />
                    </serverVariables>
                </rule>
            </rules>
            <outboundRules>
                <rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
                    <match filterByTags="A, Form, Img" pattern="^http(s)?://localhost:4533/(.*)" />
                    <action type="Rewrite" value="http{R:1}://music.flattland.com/{R:2}" />
                </rule>
                <preConditions>
                    <preCondition name="ResponseIsHtml1">
                        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
                    </preCondition>
                </preConditions>
            </outboundRules>
        </rewrite>
        <urlCompression doStaticCompression="true" />
    </system.webServer>
</configuration>

References

Some of these I didn't use, but may still be helpful, especially if you're trying to mimic nginx.

HOWTO: Configure IIS as a Reverse Proxy for the Integrated Web Server
- This site says to enable "preserveHostHeader," which I didn't do. Maybe that would remove the need to overwrite Accept-Encoding?
Setting HTTP request headers and IIS server variables
- Official MS documentation. It confusingly does two things: changes language mapping and overwrites HTTP headers via server variables
How to set the X-Forwarded-For header on IIS reverse proxy setup?
- I didn't need to do this, but nginx shows it.
Setting up Navidrome with Nginx as a reverse proxy

Flatt's Favorite Development Tools 2024

Tue, 2 Jan 2024 21:37:19 -0700

CONTENTS

My Ode to Scott Hanselman
Why Do Tools Matter?
By Requirement
By License Type
By Security
By Category
The Tools

My Ode to Scott Hanselman

Scott, you are right, this post took so long!
I could have coded an app. I could have written a song.
But I've yearned to promote my fave tools for years
For the public to read, even if nobody cares.

You're a tool nerd for sure, an App User Supreme
Trying utils in numbers I could only (of) dream.
You pointed the way, you're a software sensei,
Here's my kata in prose, my Tao (meaning "way").

You make coding real cool
Thank you, dude, and stay well.

Scott Hanselman's 2021 Ultimate Developer and Power Users Tool List for Windows - Scott Hanselman's Blog

Why Do Tools Matter?

Let me ask you something? Could you build a house using just a hand saw, hammer, manual drill, and ruler?

Well, sure you could. But why in the world would you?

The DevOps Research and Assessment (DORA) group have conistently found that when software teams can choose their own tools they are more productive and deliver higher quality work.

"Teams that can choose which tools to use do better at continuous delivery. No one knows better than practitioners what they need to be effective."

Developers are power users. In organizations, they need to be entrusted with the security privileges to easily install and remove software. That's part of their job. Which isn't to say their tools shouldn't be audited. That's good security. But security departments should partner with developers and operations to reduce friction to developing valuable software. That's a responsible use of time and funds. Removing barriers to tool choice, along with practical security measures, is analogous to letting your skyscraper contractors use whichever tools they need while following safety protocols.

Below are most of the tools I consider essential in my kit today. They've proven their worth over years and years. The list below includes some apps for SQL data reporting that may not be applicable to your environment. I'm missing several testing tools that the QA person on a team would require. Hopefully I can update with those in the future. I also include some design and testing tools that maybe you don't need to sling code but are valuable on a team. Or maybe you should try them and see!

I'm a Microsoft stack developer and my choices reflect that.

By Requirement

While all of the tools and utilities in this article are valuable, there are some without which development can't practically be done.

Must Have

Visual Studio
Visual Studio Code
LINQPad
Git for Windows
PowerBI Desktop
SQL Server Developer
SQL Server Management Studio
PowerShell 7
Insomnia
Telerik Fiddler
ShareX
Balsamiq Wireframes

High Value

Everything else!

Note It was hard leaving LINQPad out of the Must Have section. I'd hate to be without it; the ROI is incredibly high. But it's not--technically--essential. Update 2025 I've changed my mind. I've found LINQPad to be so useful and save so much time that I consider it an essential tool.

By License Type

The only types listed here are Free and Licensed. Some apps (such as LINQPad) have free versions that aren't adequate for daily, high-performance use. In those cases, they're listed as Licensed.

Licensed

Visual Studio
LINQPad
Balsamiq Wireframes
UltraFileSearch

Free

Visual Studio Code
Git for Windows
PowerBI Desktop
SQL Server Developer
SQL Server Management Studio
PowerShell 7.x
Notepad++
Azure CLI
Windows Terminal
Windows Package Manager (winget)
NVM for Windows
ShareX
Microsoft Remote Desktop (RDC) Manager
7-zip
Oh-My-Posh
~~KDiff3~~ Updated 2025
Insomnia
Telerik Fiddler
FreeCommander XE
Oracle VirtualBox
Inkscape
Paint.Net

By Security

Many apps require UAC to install, but don't require admin rights to run. They may also require UAC with an exe/winget installer but also have portable versions. Apps are categorized below by least-needed privilege. For example, Git for Windows need UAC for the exe installer but not for portable, so it's listed under portable. Likewise if it's non-UAC but also has a portable, then the app is listed as portable.

While portable apps are viable, I recommend using an installer--winget is ideal!--whenever possible. This makes it much easier to keep software up to date and secure.

Install UAC = true

Visual Studio
PowerBI Desktop
SQL Server Developer
SQL Server Management Studio
Azure CLI
Windows Package Manager (winget)
NVM for Windows
7-zip
~~KDiff3~~
Telerik Fiddler
Balsamiq Wireframes
UltraFileSearch
Oracle VirtualBox

Install UAC = false

Visual Studio Code
Oh-My-Posh

Portable

Git for Windows
PowerShell 7
LINQPad
Notepad++
Windows Terminal
ShareX
Microsoft Remote Desktop (RDC) Manager
Insomnia
Ditto
FreeCommander XE
Inkscape
Paint.Net

By Category

These categories are kind of loose, but helped me understand my own tool use.

Development

IDEs and Editors
- Visual Studio
- Visual Studio Code
- LINQPad
- Notepad++
Version Control
- Git for Windows
Terminals and Shells
- PowerShell 7.x
- Windows Terminal
- Oh-My-Posh
Software Management
- Window Package Manager (winget)
- NVM for Windows
Diff and Merge
- ~~KDiff3~~
- VS Code
Debugging
- Insomnia
- Telerik Fiddler
Other
- Azure CLI
- Microsoft Remote Desktop (RDC) Manager

Design

Balsamiq Wireframes
Visio
Inkscape
Paint.Net

Testing

Oracle VirtualBox

Data

PowerBI Desktop
SQL Server Developer
SQL Server Management Studio
Oracle IDE of some kind

General Utilities

7-zip
Ditto
UltraFileSearch
Ditto
FreeCommander XE

Documentation and Support

ShareX

The Tools

Visual Studio

https://visualstudio.microsoft.com/downloads/

UAC: Y
COSTS: Free | Individual 45/user/mo | Enterprise 240/user/mo
INSTALLATION: exe, winget

DESCRIPTION

Visual Studio has provided perhaps the best IDE for decades. Not using it for most Microsoft stack development would be like not designing skyscrapers using computer-aided design.

Visual Studio Code

https://code.visualstudio.com/download

UAC: N
COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

Several years ago Microsoft went from having the world's simplest text editor--Notepad--to creating one of the best text editors available on any platform. VS Code out of the box includes amazing features including file comparison and Git support. Its tens of thousands of extensions let you be super-productive.

Git for Windows

https://gitforwindows.org/

UAC: Y (exe, winget) N (zip) COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

Git is the de facto version control system today and Git for Windows is the must-have tool for Windows users.

PowerBI Desktop

https://www.microsoft.com/en-us/download/details.aspx?id=58494

UAC: Y
COSTS: Free
INSTALLATION: exe, winget,

DESCRIPTION

If you're creating PowerBI reports, you need this application.

SQL Server Developer

https://www.microsoft.com/en-us/sql-server/sql-server-downloads

UAC: Y
COSTS: Free
INSTALLATION: exe, winget

DESCRIPTION

When developing against a SQL database there are two local choices: Developer or Express. Developer is the superior choice because it includes all the same features as SQL Server, letting you develop with parity.

SQL Server Management Studio

https://learn.microsoft.com/en-us/sql/ssms/download-sql-server-management-studio-ssms

UAC: Y
COSTS: Free
INSTALLATION: exe, winget

DESCRIPTION

There are other really good SQL tools, but SSMS is still the best overall.

PowerShell 7.x

https://learn.microsoft.com/en-us/powershell/

UAC: Y (exe, msi, winget) N (zip, msixbundle, dotnet) COSTS: Free
INSTALLATION: exe, msi, winget, zip, msixbundle, dotnet

DESCRIPTION

There's a version of PowerShell that's pre-installed in Windows called, naturally, PowerShell for Windows. But the latest version of PowerShell--version 7--is what you want to use. It has new features and is cross-platform. It's also what's used by Azure DevOps Pipelines, so if you're writing PowerShell scripts for ADO you want to use the same version.

LINQPad

https://www.linqpad.net/

UAC: Y (exe, winget) N (zip)
COSTS: Free | Individual 125/major ver | Team 10-user 850/major ver
INSTALLATION: exe, winget, zip

DESCRIPTION

There are a few tools I always pay for because they save me (and my client or employer) ten times over. One of those is LINQPad. In truth, I only occassionally use it for database querying. I mostly use it for code prototyping, debugging, and utilities. I'd estimate using this tool saves me a couple hundred hours a year. You need to buy a license to get Intellisense and other features. It's a bargain.

Notepad++

https://notepad-plus-plus.org/downloads/

UAC: Y (exe, winget) N (zip) COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

Nowadays I use VS Code for most of my text editing. But Notepad++ still has features that make it valuable to install. For example, it has excellent search-in-files where results are output to a separate pane. I've also found it integrates better into Git as the default editor for things like git commit --amend

Azure CLI

https://learn.microsoft.com/en-us/cli/azure/

UAC: Y
COSTS: Free
INSTALLATION: winget, msi

DESCRIPTION

Sometimes you can gain real automation benefits by writing command line tools. Accessing Azure Portal and Azure DevOps via a CLI is very helpful. Here's one use case: A script that runs a batch of DevOps pipelines.

Windows Terminal

https://learn.microsoft.com/en-us/windows/terminal/

UAC: N
COSTS: Free
INSTALLATION: winget, zip, msixbundle

DESCRIPTION

When Microsoft decided to finally create a professional terminal they delivered in spades. Windows Terminal can run many shells--command, PowerShell, Bash--in a modern tabbed interface. In Windows 11 it has offically replaced the ancient command prompt.

Windows Package Manager (winget)

https://learn.microsoft.com/en-us/windows/package-manager/winget/

UAC: Y
COSTS: Free
INSTALLATION: msixbundle

DESCRIPTION

Winget is apt-get for Windows. It's Microsoft's answer to Chocolaty. It's built into Windows 11. And it's categorized by Microsoft as a developer tool. It's the easiest way to install and upgrade local software, saving developers hours of time. It reduces friction to keeping software up-to-date, which is great for security. For onboarding, a simple script can be created that allows setting up a development machine in 20 minutes instead of two (or more!) hours.

In short, winget is a great productivity tool fully supported by Microsoft.

NVM for Windows

https://github.com/coreybutler/nvm-windows

UAC: Y
COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

Developing apps using Node has a drawback: by default you can only have one version installed at a time. The solution is Node Version Manager (nvm) for Windows. This mighty tool needs to run with Admin privileges because it installs and switchs the currently active Node version. It's a critical, time-saving tool for situations like upgrading versions.

ShareX

https://getsharex.com/

UAC: Y (exe, winget) N (zip)
COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

You can pay for SnagIt and get an adequate experience. Or you can not pay for ShareX and customize your experience to be super-efficient. The time to learn this tool is well worth it. I use screen shots every day for writing documentation, creating bug reports, posting questions to other developers. Taking and editing screen shots should be as frictionless as possible. No other tool I've used does it better. You can even perform decent OCR and make short screen recordings and GIFs (very helpful for training). ShareX probably saves me a hundred hours a year.

Microsoft Remote Desktop (RDC) Manager

https://learn.microsoft.com/en-us/sysinternals/downloads/rdcman

UAC: N
COSTS: Free
INSTALLATION: winget, zip

DESCRIPTION

Sometimes you only have to log into one or two servers using Remote Desktop. But other times you need to log into quite a few and bounce back and forth between them. That's when RDC Man, from the venerable Sysinternals (part of Microsoft), is your friend. It's just a way of launching and organizing RDP sessions, but man is it helpful!

7-zip

https://www.7-zip.org/download.html

UAC: Y
COSTS: Free
INSTALLATION: exe, msi, winget

DESCRIPTION

Windows has Zip decompression built in. But 7-zip is still the tool to install when you regularly deal with compressed files. And developers deal with compressed files all the time. It's the best utility for the job, plus the 7z compression is amazing.

Oh-My-Posh

https://ohmyposh.dev/

UAC: N
COSTS: Free
INSTALLATION: exe, winget, powershell

DESCRIPTION

I do most of my Git work at the command line. I take advantage of aliases and the power that Visual Studio and VS Code don't have. The smartest thing I did a couple of years ago was install Oh-My-Posh so I can, at a glance, know the status of my repo. Just this utility has saved me from making dumb mistakes that would have cost me hours of time. I'd be foolish not to use it.

KDiff3

https://download.kde.org/stable/kdiff3/?C=M;O=D

UAC: Y
COSTS: Free
INSTALLATION: exe, winget

DESCRIPTION

Update 2025: I no longer use KDiff3. It's a good tool, but I've found that VS Code's Git 3-way merge is better. However, for folder diffing you need KDiff or something like it. (FreeCommander XE has folder compare, for example)

I'll admit right now I've never used Beyond Compare. I should evaluate it, for sure. In the meantime, what other file diff/merge tools are out there? VS Code does a good job and can be called from the Git CLI. Visual Studio's diff/merge isn't quite as good in my opinion. WinMerge--another free tool--is nice but doesn't open well from Git CLI. But it does compare folders, which VS and Code don't. And then there's KDiff3. It's hard to find the latest version of this tool, so use the link above. What I like about KDiff3 above the other tools is:

Opens quickly from Git CLI
Has the clearest 3-way merge experience
Shows character diffs
Has a good folder diff

Honestly, no tool magically resolves Git merge conflicts. They're all taking their best guess. So find a tool or two you like.

Insomnia

https://github.com/Kong/insomnia
https://insomnia.rest/

UAC: N
COSTS: Free | |Individual 5/mo | Team 12/user/mo INSTALLATION: exe, winget, zip

DESCRIPTION

Update 2025: My workplace uses Postman, so I haven't used Insomnia for a long time. I'm keeping it on the list, but I can't fully recommend it.

Postman is the big name tool for testing web services (e.g. REST APIs). But I . . . kind of . . . don't like it. Insomnia just seems like a tool focused on making the work easier, not selling me licenses. In fact, to use it for free, download from GitHub, install choosing local, and use the local scratch pad. I admit, that path is a little hidden, but it's a great way to try out the tool long term.

For QA departments, Postman may be a smarter tool and maybe it's good for developers, too. But I'd give Insomnia a fair chance.

Telerik Fiddler

https://www.telerik.com/download/fiddler

UAC: Y
COSTS: Free
INSTALLATION: exe, winget

DESCRIPTION

I don't reach for Fiddler every day. But on those days I need to know exactly what's going on with my web app traffic, I could either guess for hours or I can run Fiddler and know if a few minutes. It's an essential tool for that reason.

Ditto

https://ditto-cp.sourceforge.io/

UAC: Y (exe, winget) N (zip)
COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

A utility I didn't know I needed until I had it, Ditto was demonstrated to me by a colleague a couple of years ago. I'm amazed how often I use it, not only for simple cases (I copied something to the clipboard ten minutes ago and have since copied over it. Ditto lets me get that previous copy) but for some power-user situations. I've used it to make several dozen entries where I needed to use three or four different copy-paste operations. A real time-saver!

Balsamiq Wireframes

https://balsamiq.com/wireframes/desktop/

UAC: Y
COSTS: Trial | Individual 129/maj ver | Cloud 2 project 90/year, 20 project 490/year (unlim users)
INSTALLATION: cloud, exe, msi, winget (To install w/o UAC, VC Redist must already be installed)

DESCRIPTION

I love Balsamiq. I've used it for years. It's delightful. It's keyboard-centric, making it quick to create wireframes. The results are, by design, low-fidelity, which signals to customers and users "this is not the final design." The cloud version has collaboration features (which I haven't used). Most of all, the company has made it a joy to use.

UltraFileSearch

https://www.ultrafilesearch.com/

UAC:Y
COSTS: Trial | Individual 25/maj ver | Team(5) 20/user/maj ver
INSTALLATION: exe, msi, zip

DESCRIPTION

You can search for files and folders in Windows. You can even power search--sort of--using arcane commands. Or you can use a dedicated file search tool. VS Code has some capability in this regard, but UltraFileSearch is one I like a lot. It's worth paying for. I'm always suprised just how much I have to search source code. Visual Studio doesn't cut it for refined searching.

I also like FreeCommander's file search.

FreeCommander XE

https://freecommander.com/en/summary/

UAC: Y (exe, winget) N (zip)
COSTS: Free (x32) | Individual 20/year ver (x64)
INSTALLATION: exe, winget, zip

DESCRIPTION

One day awhile back I got tired of having a half dozen File Exporer windows open. Really tired. So I evaluated most of the "explorer replacements" out there and, while several were good, only one let me do everyting I wanted: dual-pane for files, tabs, a pane for favorites, and a pane for the tree.

FreeCommander does much more than file management, but just being able to have one window where I can easily switch folders? It's amazing how much it streamlines my work. It also has a really good file search (though I like UltraFileSearch a little better for power use), batch file renaming, and customizable tool bar where, for instance, I have a button to launch VS Code in the currently selected folder.

Oracle VirtualBox

https://www.virtualbox.org/

UAC: Y
COSTS: Free
INSTALLATION: exe, winget

DESCRIPTION

Back in the day--decades ago--I fell in love with VMWare Workstation. It was the first app that let you install an operating system inside an operating system. It was--and is--magical. But VMWare is now a behemoth. Filling the desktop user's need is VirtualBox. What good is it to a developer? Simply, it's a relatively quick way to test software simulating a regular user's machine. This can be critical for debugging. In fact, I used it while compiling this guide to test every software installation!

Inkscape

https://inkscape.org/

UAC: Y (exe, winget) N (zip)
COSTS: Free
INSTALLATION: exe, winget, zip

DESCRIPTION

By all means, pay huge amounts of money to Adobe if you're a professional corporate designer. But if you only occassionly need to create sophisticated vector graphics, Inkscape is legend. It takes some effort to learn--it doen't hold your hand--but it's worth the time.

Paint.Net

https://getpaint.net/download.html

UAC: Y (exe, winget) N (store, zip)
COSTS: Free | Individual 10/maj ver
INSTALLATION: exe, winget, store, zip (github)

DESCRIPTION

To repeat myself, by all means feed the Adobe leviathan. Photoshop is king. But for most developers, Paint.Net is plenty for basic photo retouching. It's a great tool.

Git Demand Flow

Thu, 28 Dec 2023 20:27:53 -0700

The Issue

Plenty of research says using a trunk-based version control merge/branch strategy is highly effective. But what if a team isn't ready for this?

The trunk-based strategy expects that every commit to main is ready for production (assuming it passes all automated tests).
If a commit isn't ready for production, a great technique is to hide the change behind a feature flag.

Our team has this situation:

Commits need to be tested on demand.
But only some of those commits will be deployed to production right away.

For example, we may be working on a larger feature that--for various reasons--has to be released all together. For now, we cannot use feature flags and we can't easily add more discrete testing environments.

Git Flow seems like a solution, but it still expects to merge point-in-time commits into main.

Here is an approach we're trying. It maintains two independent--but related--branches: test and main. Release branches feed main.

Rules

No PRs to test or main without a story
Latest test can always be deployed to Test
A PR to test must be QA-ready
Latest main can always be deployed to Production
A PR to main must be production-ready

Work flow

I was tempted to use feature branches for longer-lived changes. But we already link stories to features, so using a feature branch in Git seems unnecessary.

It would also require lots of rebasing and forced pulls, the combination of which is asking for trouble.

Besides branching and merging, the flow below refers to tagging stories, moving them into columns, and triggering pipelines. We use Azure DevOps for all of this. You can ignore that stuff if you want, it's not required for the branch/merge strategy.

What matters most is we

PR into test
Cherry-pick into release
PR into main

Flow

Developer begins coding for a story in a branch, e.g. clf/198222-improve-customer-grid-performance
When the story is ready for QA:
1. Tag story as Deployable
When QA requests testing one or more stories:
1. PR: merge clf/198222-improve-customer-grid-performance into test
2. Tag test branch commit to trigger pipelines
3. Remove Deployable tags
When stories are fully tested
1. Move to UAT Done
2. If deployable to production, tag as Deployable for next release
3. Move Deployable to Deploy Doing
4. Branch from main to release/[datetime]. Cherry pick story commits into release branch.
5. PR: merge release/[datetime] into main
6. Tag main branch commit to trigger pipelines
7. Delete story branches
8. Delete Deployable tags
9. Move to Deploy Done

Wrap Up

This flow seems like it will succeed in keeping both test--and especially main--branches clean until we're ready for trunk-based development.

Better Bugs and Stories

Thu, 28 Dec 2023 18:40:39 -0700

Why?

Written communication is hard. Bugs and stories too often lead to people having to unnecessarily ask someone to explain what's been written because it's vague. There's such a thing as too much detail, but too little, unclear information is more common.

This article doesn't cover all about writing good user stories or bugs. It focuses on a few practices that I've found help the most.

Bugs

The most important parts of a bug report are A) the steps to reproduce the problem, and B) clarity of what the problem is.

There are many audiences for bugs: the user who's reporting, the developer who's fixing, the product manager or business analyst who's communicating the bug from the user to the team.

All of these audiences have different mental models of the application and often assume others know what they do. How do we make sure the steps are clear? Here's one tip I like.

Write the repro steps as if you were training a new employee

Here's how the initial user (who could be a developer or product owner, really anyone) might initially desribe a bug.

Help! When I search for a customer it should show me the last modified date but isn't.

Clarifying this bug may require a few messages or, ideally, watching the person do the work. The bug report might end up like this.

TITLE: Solaris Activium Search not showing last modified for Nevada customers

REPRO STEPS
1. Open Solaris Activium
2. Choose Menu > Search > Customer Search
3. Enter last name "Calypso", first name "Bernard" and Search. Note she lives in Nevada.

Expected: A last modified date within the last few years
Actual: 0000-00-00

4. Enter last name "Chattergee" first name "Parag" and Search. Note he lives in Maine.

Actual: 2019-03-24

[screen shot]

MORE INFORMATION
They're only seeing this happen with customers who are in Nevada, but 
haven't tested all states.

ACCEPTANCE CRITERIA
(optional if obvious from the bug.)

Last modified date is shown for customers in all states.

What helps the person who opens the bug?

Which system/app is involved?
What are the exact steps the user performed?
What was expected? What was actually seen?
Sometimes a screen shot helps

"Exact steps the user performed" is important. Often someone familiar with the application will try to reproduce the problem but using different steps, leading to "I can't reproduce" confusion.

Note that while the user might consider the bug fixed if Nevada customers show last modified, the developer should have realized other states could be affected, leading to the more thorough acceptance criteria.

Stories

Stories, aka "user stories," are used for planning. They should contain the least detail necessary to understand what the story's about and how to know it's done. They promote conversation. A story will likely change as it gets closer to release.

There are several techniques to help define the story's value. A common one is the template "As a [Role], I [need/want], because [value]. Here's an example.

TITLE: Implement Solaris Activium login reset 

VALUE
As a User, if I've forgotten my password I want a 
way to easily reset it so I can quickly get back to work.

MORE INFORMATION
Today, if a user forgets her password she has to submit a support 
ticket. Reviewing the last six months of help desk data, it takes 
an average of four hours for the password to be reset. These users 
often have deadline-based work, so those delays have a serious cost.

DEVELOPER NOTES
[jj] I think we can do this using the standard forgot password pattern.

ACCEPTANCE CRITERIA
The new flow is

*   User clicks "forgot password" on login page.
*   User enters email address and submits.
*   Email arrives in under a minute with link to reset.
*   Link opens a page to enter the new password twice. Password is validated.
*   After submitting valid password, user is immediately taken into app.

The key elements above are:

We know who, what, and why, stated as simply as possible
We understand the business value, probably a result of discussion with the user and developers
Developers can capture key discussion points.
The story is testable, and the test is simple.

Wrap Up

Hopefully this is useful. What both bugs and stories boil down to are:

What are we trying to do?
Is it clear to everyone?
How will we know it's done?

Concise, clear sentences make a big difference. This all takes practice but pays for itself quickly.

One Sheet Summary: Art of Agile Development - Planning

Sun, 26 Nov 2023 15:49:11 -0700

I make these to post on my wall and help me learn the subject. Be sure to read the book!

This summary is only for the chapters on planning! And it isn't at all complete.

Download the PDF Version

.NET Framework vs Core Environment Configuration

Sun, 15 Oct 2023 09:34:52 -0600

The Source Code
The Crucial Difference
What's In Store
Brief History
Why Run-Time Configuration Matters: Build Once, Deploy To Many
Show Me the Code!
Time Out! What's With DevelopmentShared? And How Does All This Work?
Proving How It Works
Wrap Up

UPDATE 2025
This article was intended to simply compare Framework and Core's default configuration approaches. However, reader Phil Ashby (thanks, Phil!) asked me to point out that Core (now just ".NET")-style configuration can be used in Framework. There are two approaches.

Ben Foster showed in 2016 how to use Core-style configs in Framework. I've used this approach myself. Using .NET Core Configuration with legacy projects

Unknown to me until Phil pointed it out, Microsoft included native support for ConfigurationBuilder starting in 2017 with .NET Framework 4.7.1. I haven't read this article, but it seems like a better solution. Configuration builders for ASP.NET

The Source Code

Code is found at:

https://github.com/bladewolf55/ConfigDemo

The Crucial Difference

.NET Framework applies environment configurations at build time, transforming environment-specific files to create a single configuration file for the deployed application. The application knows what environment it's supposed to be in, regardless of where it's deployed.

.NET/Core applies environment configurations at run time, using a specific environment variable, and can consume many configuration sources. The application asks what environment it's deployed in.

What's In Store

To show how Framework and Core differ, I'll show two ASP.NET MVC apps that do the same thing using both configuration strategies.

Brief History

.NET's configuration strategy has a checkered past. The .NET Framework depends on a single web.config or app.config¹. This is a hard dependency, meaning the file must exist. There's no way to construct a configuration in memory, and if you want to change a configuration value you have to save to the config file.

Over time, Microsoft tried various ways to allow changed the config file. The most common is arguably XML Transforms.

Create a new build configuration such as "Staging"
Add the corresponding config file, web.Staging.config
Write transformations that update the base web.config
Apply those transformations when publishing

There are several problems with this approach.

It conflates build configuration with environment configuration.
It's build-time, as noted above.
By design, transformations can not be applied during development. You don't run the app in Visual Studio using the Staging configuration.

The last item was a sticking point for developers. Whether we shouldn't be running other than locally, we often need to. So, developers found various, non-supported ways to handle this. The most common is using a pre-build target to apply the transform.

This led to yet another problem: the web.config file kept changing and, with the rise of version control, was either accidentally checked in or had to be undone. There are some clever ways to manage that, but they're fundamentally workarounds.

Microsoft pretty much fixed all these problems in .NET Core. It was clear that developers needed to be able to consume environment-based configurations from arbitrary sources during run time.

In .NET/Core, the build configuration (Debug, Release) are separate from environment configurations. Build configurations determine things like assembly names, optimization settings, and whether you can debug.

I want to be able to Debug in any environment!

No matter the source, all environment configurations must be key-value pairs. A simple way to understand environment configurations is also a simple, supported case: when the application runs, it reads all its configuration from system environment variables.

Why Run-Time Configuration Matters: Build Once, Deploy To Many

Quick quiz: if I build the same .NET Framework code using three different transform files, are they all the same or different?

It's tempting to say, "Well, the code is the same, just the configs are different." But that's technically false. They are three different binaries. The code, in some way, could be different. This breaks a principle of continuous deployment.

Build once, deploy to many

We want to have one build artifact which we then deploy to any environment. This way, we know the code is the same, and the only difference is the environment. We also save considerable time in our CI/CD process.

Show Me the Code!

Our web site does just a couple of things:

Display an environment-based setting called TestKey
Display a customer from the environment's database

Database

The app assumes using a SQL Server; modify to your needs. Here's a script for creating the database, tables, and data.

use master
go
create database ConfigLocal
go

use ConfigLocal
go
create table Customers (
	CustomerId int primary key identity,
	Name varchar(max)
)

insert Customers(Name) values ('Local Louise')
select * from Customers
------------------------------------------------------

use master
go
create database ConfigDevelopmentShared
go

use ConfigDevelopmentShared
go
create table Customers (
	CustomerId int primary key identity,
	Name varchar(max)
)

insert Customers(Name) values ('Development Shared Dagmar')
select * from Customers
------------------------------------------------------

use master
go
create database ConfigStaging
go

use ConfigStaging
go
create table Customers (
	CustomerId int primary key identity,
	Name varchar(max)
)

insert Customers(Name) values ('Staging Sierra')
select * from Customers
------------------------------------------------------

use master
go
create database ConfigProduction
go

use ConfigProduction
go
create table Customers (
	CustomerId int primary key identity,
	Name varchar(max)
)

insert Customers(Name) values ('Production Pavla')
select * from Customers
------------------------------------------------------

.NET Framework Version

We're going to fly through the coding part while calling out what matters.

Create new ASP.NET Web Application (.NET Framework) project named "ConfigFramework"
Choose MVC template
Add EntityFramework NuGet package

Add Data folder

Add Customer.cs

namespace ConfigFramework.Data
{
    public class Customer
    {
        public int CustomerId { get; set; }
        public string Name { get; set; }
    }
}

Add ConfigDb.cs

using System.Data.Entity;

namespace ConfigFramework.Data
{
    public class ConfigDb: DbContext
    {
        public DbSet<Customer> Customers { get; set; }

        public ConfigDb(): base("name=ConfigDb") { }

    }
}

Add Models/CustomerViewModel.cs

namespace ConfigFramework.Models
{
    public class CustomerViewModel
    {
        public int CustomerId { get; set; } 
        public string Name { get; set; }
        public string TestKey { get; set; }
    }
}

Replace code in Controllers/HomeController.cs

using ConfigFramework.Data;
using ConfigFramework.Models;
using System.Linq;
using System.Web.Mvc;

namespace ConfigFramework.Controllers
{
    public class HomeController : Controller
    {
        ConfigDb db = new ConfigDb();

        public ActionResult Index()
        {
            var customer = db.Customers.First();
            var model = new CustomerViewModel()
            {
                CustomerId = customer.CustomerId,
                Name = customer.Name,
                TestKey = Settings.TestKey
            };
            return View(model);
        }
    }
}

Replace code in Views/Home/Index.cshtml

@model ConfigFramework.Models.CustomerViewModel

<p>Customer:  @(Model.CustomerId.ToString() + " " + Model.Name)</p>
<p>Key: @(Model.TestKey)</p>

How Do We Read the Environment Configuration?

Add at root Settings.cs

using System.Web.Configuration;

namespace ConfigFramework
{
    public static class Settings
    {
        public static string TestKey = WebConfigurationManager.AppSettings["TestKey"];
    }
}

Update web.config

<!--> Add under configuration > configSections-->
<connectionStrings>
    <add name="ConfigDb" connectionString="Server=.;Database=ConfigLocal;Trusted_Connection=True" 
        providerName="System.Data.SqlClient"/>
</connectionStrings>

<!-- Add to appSettings> -->
<add key="TestKey" value="Local"/>

Open Build > Configuration Manager
Drop down Active solution configuration > New
Name = "Development", Copy settings from = "Debug", Create new project configurations = checked
OK
Do the same to create Staging and Production configurations
If you don't immediately see the Web.[environment].config files under web.config
1. Right-click web.config
2. Choose Add config transform

Update Web.Debug.config

<?xml version="1.0" encoding="utf-8"?>

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <connectionStrings>
        <add name="ConfigDb" connectionString="Server=.;Database=ConfigLocal;Trusted_Connection=True" 
            providerName="System.Data.SqlClient"
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </connectionStrings>
    <appSettings>
        <add key="TestKey" value="Local" xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
    </appSettings>
</configuration>

Similarly, update Development, Staging, and Release with these values:
1. Development: Database=ConfigDevelopmentShared, TestKey value="Development"
2. Staging: Database=ConfigStaging, TestKey value="Staging"
3. Production: Database=ConfigProduction, TestKey value="Production"
Using an external editor, modify ConfigFramework.csproj. Add this task node at the bottom.

This is the magic sauce that allows running the app in Visual Studio using different configurations
```
<Target Name="BeforeBuild">
    <TransformXml Source="Web.config" Transform="Web.$(Configuration).config" Destination="Web.config" />
</Target>
```

Run It
Setting the configuration to Debug and pressing F5 should, at this point, open the web site and display something like this:

You might get a message about enabling debug. Go ahead and do that. We aren't going to disable debugging in our environment files, but in a real application we would.

Changing the configuration displays different data.

Key Points

Environments are linked to build configurations.
Web site is run using one IIS Express setup, regardless of configuration.
.NET Framework has no dependency injection out of the box. So, we're using a global, static Settings file. This means unit testing depends on the unit testing project having a web.config file that's configured appropriately rather than injecting configurations.
While it's possible to get settings from other sources (such as a database), it's custom work.

.NET/Core Version

The steps here are very similar in .NET Core 3+ and .NET 5+. This code uses .NET 6 and includes improved C# language features such as file-scoped namespaces.

Create a new ASP.NET Core Web App (Model-View-Controller) project named "ConfigCore"

Important Be sure to use the Model-View-Controller template
Add Microsoft.EntityFrameworkCore.SqlServer NuGet package

Add Data folder

Add Customer.cs

namespace ConfigFramework.Data;

public class Customer
{
    public int CustomerId { get; set; }
    public string Name { get; set; } = string.Empty;
}

Add ConfigDb.cs

using Microsoft.EntityFrameworkCore;

namespace ConfigFramework.Data;

public class ConfigDb: DbContext
{
    public DbSet<Customer> Customers { get; set; }

    public ConfigDb(DbContextOptions options) : base(options) { }
}

Add Models/CustomerViewModel.cs

namespace ConfigFramework.Models;

public class CustomerViewModel
{
    public int CustomerId { get; set; } 
    public string Name { get; set; } = string.Empty;
    public string TestKey { get; set; } = string.Empty;
}

Replace code in Controllers/HomeController.cs

There's more code, but we're also doing more with dependency injection

using ConfigFramework.Data;
using ConfigFramework.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

namespace ConfigCore.Controllers;

public class HomeController : Controller
{
    readonly ILogger<HomeController> _logger;
    readonly ConfigDb db;
    readonly Settings settings;

    public HomeController(ILogger<HomeController> logger, ConfigDb db, IOptions<Settings> settings)
    {
        _logger = logger;
        this.db = db;
        this.settings = settings.Value;
    }

    public IActionResult Index()
    {
        var customer = db.Customers.First();
        var model = new CustomerViewModel()
        {
            CustomerId = customer.CustomerId,
            Name = customer.Name,
            TestKey = settings.TestKey
        };
        return View(model);
    }
}

Replace code in Views/Home/Index.cshtml

@model ConfigFramework.Models.CustomerViewModel

<p>Customer:  @(Model.CustomerId.ToString() + " " + Model.Name)</p>
<p>Key: @(Model.TestKey)</p>

How Do We Read the Environment Configuration?

Here's where we see how very different Framework and Core are

Add at root Settings.cs

Note this does not directly read configurations. Properties get set later.

namespace ConfigCore;

public class Settings
{
    public const string AppSettings = "AppSettings";

    public string TestKey { get; set; } = String.Empty;
}

Update Program.cs

Set up the DbContext and configuration file dependency injection

// Add after builder.Services.AddControllersWithViews();
builder.Services.AddDbContext<ConfigDb>(options => options.UseSqlServer("name=ConnectionStrings:ConfigDb"));
builder.Services.Configure<Settings>(builder.Configuration.GetSection(Settings.AppSettings));

Add a file named appsettings.Development.json

The section names are arbritary, but we still have a supported convention of sections named ConnectionStrings and AppSettings.

{
    "Logging": {
        "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
        }
    },
    "ConnectionStrings": {
        "ConfigDb": "Server=.;Database=ConfigLocal;Trusted_Connection=True;TrustServerCertificate=true;"
    },
    "AppSettings": {
        "TestKey": "Development"
    }
}

Add the remaining files with these environment names:

These files are one of several source that .NET checks for when configuring
1. DevelopmentShared: Database=ConfigDevelopmentShared, TestKey value="Development"
2. Staging: Database=ConfigStaging, TestKey value="Staging"
3. Production: Database=ConfigProduction, TestKey value="Production"

Update Properties/launchSettings.json. Replace the IIS Express entry with these new entries.

"IIS Express Development": {
  "commandName": "IISExpress",
  "launchBrowser": true,
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
},
"IIS Express Development Shared": {
  "commandName": "IISExpress",
  "launchBrowser": true,
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "DevelopmentShared"
  }
},
"IIS Express Staging": {
  "commandName": "IISExpress",
  "launchBrowser": true,
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
},
"IIS Express  Production": {
  "commandName": "IISExpress",
  "launchBrowser": true,
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Production"
  }
}

Run It
Keep the build configuration as Debug, choose the IIS Express Development runtime configuration and F5 to run.

You should see this:

Key Points

Build configurations are not usually customized
IIS Express can start as other environments
Environment is an environment variable, ASPNETCORE_ENVIRONMENT
Environment settings come from many sources, including appsettings.[Environment].json files.
launchSettings.json is used to set the environment variable for local development.

Important
It may not be obvious, but if you deployed the application to a web server running IIS and wanted it to run as Staging, you would have to add/set the ASPNETCORE_ENVIRONMENT to "Staging". Without that, the app will run as Production by default.

Time Out! What's With DevelopmentShared? And How Does All This Work?

In .NET/Core

WebApplication.CreateBuilder reads a bunch of configuration sources by default, in a specific order.
The "Development" environment has special behaviors that you don't know about unless you read the documentation, which will catch you by surprise.
"Development" is intended for local work

There's some problematic--but understandable--mental modeling at work here that I've seen over the years. Just as Microsoft conflated build and environment configurations, developers have conflated Debug and Development. .NET Framework accidentally encouraged developers to think of Debug as "local development." Many teams have a shared development environment (shared web and database). So, they naturally added a Development configuration that meant "remote."

In .NET/Core, Debug has nothing to do with environment, and Development equals local. This is stated in the documentation, and is evident in code like this from Program.cs

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

Development is the environment where we'd be calling other services with local ports, such as https://localhost:50334.

But more importantly, when the configuration is built up, if the ASPNETCORE_ENVIRONMENT environment is "Development", user secrets are read if they exist. This is important for keeping sensitive information secure.

Default application configuration sources

I don't like it, but as far as I can tell these hidden behaviors are only enabled if ASPNETCORE_ENVIRONMENT is set to "Development". Not "Dev", and not any other user-defined value. You can, of course, easily customize the builder, but it's critical to know the default behaviors.

Also, I prefer sticking with defaults when I can.

So, that's why I added a DevelopmentShared environment. I would assume that any secrets needed in a shared environment come from a shared source such as Azure Key Vault.

How many configuration sources are looked up by default? Six, and in this order. The later sources will override values of the same keys in earlier sources.

Fallback host configuration
appsettings.json
appsettings.[Environment].json
User secrets
Environment variables
Command-line arguments

Proving How It Works

As stated earlier, one goal of the new configuration approach is "build once, deploy to many," meaning I should be able to control my application's settings without changing the appsettings files. Let's try that.

Run using IIS Express Staging.
You should see customer "Staging Sierra" and key "Staging"

We'll run the app using a different environment, similar to running in IIS. For convenience, we'll do this from the command line with in-process environment variables.

Open PowerShell

Run

# cd [path/to/ConfigCore solution]
$Env:ASPNETCORE_ENVIRONMENT = "Production"
dotnet run --project ConfigCore --no-launch-profile

The site runs using the Kestral webhost. Open whatever URL is displayed, typically http://localhost:5000

You should see customer = "Pavla" and key = "Production"

Ctrl-C to stop the site.

Run

$Env:AppSettings__TestKey = "Blamo"
dotnet run --project ConfigCore --no-launch-profile

Once running, refresh the page.

The key should change to "Blamo."

Why is the environment variable name AppSettings__TestKey with the double-underscore? That's a Microsoft convention that allows converting the key to a hierarchy of the form "AppSettings:TestKey". In fact, the json file also converts to that format, as does any other configuration source. The double-underscore works with Linux environment variables.

When you run using Visual Studio, ASPNETCORE_ENVIRONMENT is usually set in launchSettings. But it doesn't have to be. If you delete the environmentVariables key, the app will either run as Production (the default) or as whatever is set for ASPNETCORE_ENVIRONMENT in the user profile or system environment variables.

Note: Remember you have to close/reopen Visual Studio to see new environment variable changes.

Wrap Up

Microsoft fundamentally changed how configuration works in .NET/Core compared to Framework. They solved many problems and provided flexible and testable methods. The biggest barrier I've seen to using the new configuration strategies is understanding what changed and how they're intended to work.

Because, I guess, Microsoft believed two names were better than one. So far I haven't found an article on why they used two names.↩

One Sheet Summary: Software Engineering at Google - Testing

Sat, 12 Aug 2023 12:30:00 -0600

I make these to post on my wall and help me learn the subject. Be sure to read the book!

This summary is only for the chapters on testing! And, it's kind of messy. You need to read those chapters yourself.

Download the PDF Version

Getting Started With Software (and Business and Life) Skills - 2023

Sat, 21 Jan 2023 09:00:00 -0700

Contents

Why Am I Writing This?
Principles Du Jour
The Big Hitters
Learning
Fufillment
Productivity
Business
Communication and Presentation
Programming-Specific
Appendix A - Skills (I Think) Software Developers Need to Cultivate
Appendix B - Everything You Might Need to Know To Create an Enterprise-Level Web Application

Why Am I Writing This?

I wrote my first version of this article in 2018, inspired by a young violinist-turned-developer. This time I'm thinking about some colleagues who are already in the field and wondering what might help them in their careers.

What interested me was how to answer a question: What do I think a junior software engineer needs to know?

Most of what I wrote in 2018 holds today, so there's some copy/paste going on below, but I've asked, "What matters to me now?"

The answer has almost nothing to do with programming. Oh, sure, I could list a whole bunch of programming resources that even I haven't read. But curious developers eventually find those. What I think, based on over twenty-five years of experience in the industry (plus fifteen years in retail, food service, and other jobs before that), is that a successful, fulfilled person needs to:

Learn how to learn
Know what it means to know something
Communicate well in good and bad situations
Find a job that aligns with one's purpose and values
Savor life

Are there skills specific to being a programmer? Sure. See Appendix A. But I think they don't matter without the basic human stuff. You're not going to find (much) fluff below, because one of my mottos is "show me the science."

So . . . here we go!

Principles Du Jour

Develop skills. Knowledge will come.

Little habits add up.

The Big Hitters

Last time I chose just three books/articles. I can't do that this time. These are my current top recommendations.

Good Habits, Bad Habits

There are other good books on habit-forming out there, but Dr Wood is a premier researcher on the subject. When about 40% of your life is habits, it's a good idea to turn them to your benefit.

Leadership is Language

Combining current science with compelling, practical stories, submarine captain David Marquette explains how and why he transformed himself from a command-and-coerce leadership style to collaborate-and-improve. It was literally a matter of life or death. I recommend this book all the time.

Crucial Conversations

I think the essence of this book is, "Be 100% honest, 100% respectful, and keep it safe." I've always been good at the first one . . . not so good at the other two. This book helped me improve my relationships.

Drive: The Surprising Truth About What Motivates Us

Daniel Pink delivers one of the most important books I've read on motivation.

Getting Things Done

I've used, adapted, and revisited GTD for over ten years. It's helped me tremendously. In my view, Allen's crucial messages are:

Get everything you want to do out of your head and into a system you trust.
The purpose of a personal productivity system is to reduce stress, not get more done.

Career Lab

This is a departure from the above books. Are you trying to figure out what your career should be like? Or considering transitioning? Bill is a consultant, and if you can afford to you should pay him for his expertise and experience. For those who can't, he's provided a real treasure: his entire methodology is on his web site. I took a month to work through all his exercises and they really focused me on my values. Hard work, worth it.

Learning

The Making of an Expert - Harvard Business Review
Rapid Learning - 9 Articles Reviewed <= my article

Fufillment

The Science of Well-Being | Coursera <= Fantastic! Thank you Dr Santos!
Character Strengths Survey: VIA Character <= one of the board members of VIA is Dr Martin Seligman, author of the books Learned Optimism and Authentic Happiness
Healthy Minds App <= the only app on the lists. It's meditation, but also work, and also science!

Productivity

7 Habits of Highly Effective People
Randy Pausch, The Last Lecture: Achieving Your Childhood Dreams - YouTube <= This was literally Dr Pausch's last lecture: he had cancer and a few months to live. Watch this to learn about being human.
The Last Lecture -- Randy Pausch <= and read his book, too
The 50-10 Time Box - Revising Pomodoro For Software Development <= my article

Business

Business Plans
In my 2018 meeting, I was asked about business plans. I have limited experience writing a business plan, and I knew there'd be plenty of resources available online, such as those listed.

Here's my opinion: unless you're seeking investors or a loan, the point of working on a business plan is to get you thinking, and to prepare for conversations with other professionals. This quote sums that up nicely.

"In preparing for battle I have always found that plans are useless, but planning is indispensable." --Dwight D. Eisenhower

Communication and Presentation

Despite not listing any resources below, communication and presentation might be the most important area any person can work on.

Interpersonal (Toastmasters, acting, practice presentations and record them).
Simple courtesies: thank-you notes, formalities, emails.
Follow through. Under-promise, over-deliver.

Programming-Specific

Developing a software engineer curriculum is hard, because there are about twenty subject areas. Start with what interests you, the rest will follow. See Appendix B for an overwhelming list of what it can take to write a single, professional web application.

Learn about the fundamentals of programming and what's physically happening in the computer. A lower-level language like C++ helps with this, but don't learn the language, just the concepts. A partial list: what are . . .
- Memory addresses
- Arrays
- Collections (such as linked lists and dictionaries)
- Sorting
- Loops
- Iterating and Enumerating
- Objects
Manifesto for Agile Software Development
Principles Behind the Agile Manifesto
Fundamentals of eXtreme Programming/Scrum/Kanban/Lean. Try one (I like Kanban).
Accelerate: The Science of Lean Software and DevOps <= One of the most important books on development practices today
The Art of Agile Development <= I trust James Shore's approach and understanding. It's not faux-Agile.
Podcast: Developer Tea <= Ten minute programs about improvement. I love this show.
Find the [your-language/platform-here] version of Morning Dew - Daily links for Windows and .NET developers.
Automate repetitive tasks
Systematize administrative routines (tasks, calendar) (plain text is great). That is, make it easy to practice GTD or whatever method you choose.
Tools are an aid, not an end. Learn your tools, but don't become a tool junkie.
Be ruthless about maintainability (and maintenance)

Appendix A - Skills (I Think) Software Developers Need to Cultivate

Sorry, I know I'm all about evidence, but I haven't researched this. Here is my opinion on skills/traits specific to software development.

Puzzle/problem solving. Programmers have to be able to solve problems. In my opinion, the very best are interested in how to solve problems multiple ways, and never think they have the only right answer.
Tenacity. Programmers are faced with tasks that take hours, days, or months to accomplish. They face problems that often don't have obvious or simple answers. They have to keep after it. And they're sitting in a chair, which is completely unhealthy.
Abstract thinking. This is a fact, because software is an abstraction. Programming is one of the few fields where what you see is not what you get. Developers stare at words that are instructions later interpreted to produce something someone sees. It's not natural or easy. Imagine your job was to describe, in braille, how to write an English document that explained all the steps to painting Van Gogh's Starry Night, and if the painting doesn't look right the braille book doesn't open.
Communicating complexity simply. On a scale of 1 to 10, most programmers reach about a 2 on this. A program is like a night at the theater (or movie, or symphony). You, the audience (manager, user) have no idea what it took to create. It looks simple, it must have been. Developers, especially seniors, must be able to explain how something seemingly simple will work, and why it will take a year to do it.
Understand everyone else's job. Scale of 1 to 10: most programmers are a 3 (but think they're a 7). This really depends on what area of software you're working on, but it's rare for programmers to work on software they use. A consulting shop will work for all kinds of clients. In addition to the gobs of information about their own jobs, programmers often need to understand essentials of diverse fields. I, for example, have needed to rapidly learn about: accounting, manufacturing, aircraft maintenance, and radio-nucleotide decay, to name a few.
Research. Programmers need to be able to figure out how to query the internet for information, then they have to evaluate the dozen different answers and determine which, if any, fit the issue at hand. I spend as much time researching as I do programming.

Appendix B - Everything You Might Need to Know To Create an Enterprise-Level Web Application

Don't worry, I promise you'll get there. And most of the time, you'll work with other people who know the stuff you don't.

These lists are heavily weighted toward the Microsoft development stack, because that's what I know.

User Interface

IDEs: Visual Studio, Visual Studio Code, text editor(s),
Design Prototyping: Balsamiq
Design Images: Photoshop/GIMP/Paint.Net, Illustrator/Inkscape
Image Formats: JPG, PNG, GIF, SVG
HTML
CSS
CSS preprocessors (Less, Sass)
Dynamic web page languages and templates: WebForms, Razor forms, Blazor
Javascript language
Javascript server-side development: Node
Javascript frameworks: Angular, React, JQuery
Javascript style checking: ESLint
Javascript Unit Testing: Jasmine, Karma, Angular-mocks
Package Managers: NPM
Integration Testing: Selenium
Authentication: OAuth, OpenID
Security: CORS, Cross-site injection
Performance
Other tools: Chrome F12, Fiddler
Concepts: page layout, colors, user experience, accessibility (handicapped), minification, HTTP protocol, MVVM, MVC (specifically views), REST, mocking, dependency injection

Web Service

IDEs: Visual Studio, text editor(s)
Diff and Merge: KDiff3, WinMerge, Beyond Compare
Languages: C#, VB.Net
HTTP
REST
WebAPI (models and controllers)
SOAP
Package Managers: NPM, NuGet
Unit Testing: MSTest, xUnit, NSubstitute
Dependency Injection/Inversion of Control: .NET Core dependency framework
Authentication: OAuth, OpenID
Security: Cross-site injection, SQL Injection,
Performance
Other tools: Fiddler, PowerShell
Logging: NLog, Elastic Search, Application Insights
Architecture: Onion, distributed, (micro)service-oriented
Concepts: networking, routing, view models

Web Server Back End

IDEs: Visual Studio, text editor(s)
Diff and Merge: KDiff3, WinMerge, Beyond Compare
Languages: C#, VB.NET
HTTP
MVC (specifically models and controllers)
ORM: Entity Framework, NHibernate, Active Record
Architecture (layers, onion,...)
Web Servers: IIS, Apache, Node.js
Javascript server-side development: Node
Package Managers: NPM, NuGet
Unit Testing: MSTest, xUnit, NSubstitute
Dependency Injection/Inversion of Control: .NET Core dependency framework
Authentication: OAuth, OpenID
Security: Cross-site injection, SQL Injection,
Performance
Logging: NLog, Elastic Search, Application Insights
Architecture: Onion, distributed, (micro)service-oriented
Concepts: networking, routing, view models
Other tools: PowerShell
Concepts: networking, routing, data modeling, business entity modeling, business rules, test-driven development, REST, mocking, dependency injection

Data Persistence

IDEs: SQL Server Management Studio, LINQPad, text editor(s)
Languages: T-SQL, LINQ,
Databases: SQL (Microsoft, Oracle), No-SQL (MongoDB, Redis)
ORM: Entity Framework, NHibernate, Active Record
Authentication (network)
Security
Performance
Other tools: Redgate, PowerShell
Concepts: database design, data modeling, relational design

Version Control

Source control systems: Git
IDEs: command line, Visual Studio extensions, VS Code extensions, Git Kraken
Other tools: GitHub, BitBucket, GitLab

Methodology

Development Approaches: Agile, Waterfall, Lean
Agile methodologies: Scrum, Kanban, eXtreme Programming
Project/Task Management: Kanban/Scrub board, Azure DevOps
Issue Tracking: Azure DevOps, GitHub, GitLab, BitBucket
Architecture Approaches: N-Tier, Domain-Driven Design, Onion, Service-Oriented, Microservice, Distributed
Messaging: service bugs, message queues
Continuous Integration/Release: Azure DevOps Pipelines (YAML-based), Infrastructure-As-Code
Concepts: organization, teamwork, communication, creativity, problem-solving, estimating

Testing

Unit: Javascript, web, back-end, mocking, automated
Integration
Acceptance
Exploratory
My current favorite unit testing stack:
- xUnit
- NSubstitute
- FluentAssertions

Platforms

Cloud Hosting: Azure, Amazon Web Services, Google Cloud
Docker

Miscellaneous

Microsoft Office (Word, Excel, PowerPoint)
Email
Stack Overflow web site for researching problems

Why I Don't Use Dark Mode - Science!

Wed, 14 Dec 2022 09:31:43 -0700

A colleague asked my thoughts about dark vs light modes, so here's the quick answer I gave him. It doesn't have my usual list of references, you can do your own research this time!

Generally speaking, our eyes work less when reading dark text on a light background. When trying to read light next on a dark background, our pupils dilate, resulting in the text being fuzzier and both our eyes and brain working harder to read.

There are exceptions you might see, such as older footage of air traffic control at night where the text is orange. But that's only text, not our graphics-heavy displays, and those orange (or green) choices were based on some science.

Reducing screen brightness and color range may--probably does?--help reduce eyestrain in a dark environment. I haven't checked the research on that.

Personally, I generally configure my computer/apps this way:

Use a dark, non-distracting wallpaper (often a single color)
If the app allows, use darker backgrounds for "background" areas.
Use dark text on light backgrounds.

I use f.lux to manage my screen color/brightness. I find it better than Windows's built-in utility. I've adjusted it to what's comfortable for both day and night (do enable the extended color range). If I ever have to edit images at night, I need to disable f.lux if I care about color accuracy.

One other concern I have--my opinion, not researched--is that our brains are evolved to be more afraid in dark environments and light text on a dark background might be triggering my sympathetic nervous system (fight/flight). I don't want any more stress in my life than needed.

Dark modes look cool, but I abandoned them quite a while ago based on the evidence as I understand it.

I take it back: here's one reference.

Dark mode isn't as good for your eyes as you believe | WIRED UK

The Mythical Man-Month: A Short Review of the Essential Essays

Fri, 9 Sep 2022 19:20:49 -0600

A book club I belong to agreed to read Frederick P. Brooks's seminal essay collection The Mythical Man-Month. We somewhat abandoned the book, finding a lot of it hard to relate to because we don't write operating systems for specific hardware in a time-sharing environment. Plus there's no audio version, which is how some of the members like to read. I promised the group I'd read some specific essays because I wanted to, and report back.

I've made good on that promise. I think the following are worth reading for a few reasons, which I touch on below. Something not clear initially is when the essays were written. I think that's important for the context, so include what the dates seem to be.

The Tar Pit (1975)
While not essential, this short essay nicely discusses what makes software hard and enjoyable. I think most of what Brooks says holds true today.

The Mythical Man-Month (1975)
For the title essay, the thesis has held up; adding developers (to a late project) doesn't reduce time-to-completion. Communication is a core challenge of software shops. When new developers are added, there's significant ramp-up time for them, plus other employees' training time devoted to them--taking time away from their own days.

No Silver Bullet (1986)
This is Brooks's other most famous essay, written just as microcomputers are coming on the scene. In it he proposes software development won't see magnitudes of performance improvement from any single tool or process. He also breaks down why that is, and comparing software development to hardware development makes an observation I hadn't considered: it's hardware development that's the outlier. The incredible advances in power coupled with reduced cost hadn't--and haven't--happened in any other industry.

Reading this essay is watching history unfold. Brooks is excited about new approaches--such as objective-oriented programming!

'No Silver Bullet' Refired (1995)
Here, Brooks examines his own essay nine years later. What a difference those years make! And yet, he argues that there is still no single silver bullet despite many advances. He discusses the various critiques of his essay, acknowledges where they're valid, points out where they're not. I enjoyed that he quotes Capers Jones on the subject of productivity.

"NSB," like most writings at the time, was focused on productivity, the software output per unit of input. Jones says, "No. Focus on quality, and productivity will follow."

I completely agree.

The Mythical Man-Month after 20 Years (1995)
This might be my favorite essay. Brooks discusses his entire book, where he was right, and where he was wrong. With gracious humility, he says, "I dismissed Parnas's concept [of information hiding] as a 'recipe for disaster' in Chapter 7. Parnas was right, and I was wrong."

He reveals discussions with the great James McCarthy of Microsoft who pioneered incremental and iterative processes we take for granted (even when business still don't do them!). But mostly, this essay is a snapshot of the industry approaching a turning point of both powerful personal computers and, in a few years, the codification of Agile values and principles. He names bunches of software, a lot I recognized, and most of which is no longer in use.

1995 was only a year after I entered the computing industry. I wish I'd found this book then, though I wouldn't have understood it. So much of what we talk and read about seems new, but Brooks and his colleagues were struggling with--and solving--these problems already.

We owe these masters a debt, and maybe that's why I'm glad I didn't give up on reading more of the book. I feel I've, in a small way, said "thank you" to those who came before me and made my career possible.

One final item. While the essay Why Did the Tower of Babel Fail didn't make my list, I wrote a fuller article about it on my blog. It disputes Brooks's Tower metaphor, and won't be to everyone's taste, but here it is for you to decide for yourself.

Meditation On The Mythical Man-Month: Who Failed On The Tower Of Babel Project?