Creating a V2, which clearly places emphasis on risk over intention

[arlobelshee]

This is a backwards-incompatible change.

I've been observing for a while that most users of the current notation think of the intention first, and then hand-wave the risk level. My goal for even using this notation is to become aware of risk on a commit-by-commit level. Thus I want to separate the moment where someone thinks / labels risk from the moment when they label intention.

Since I'm breaking compatibility anyway, now seemed a good time to ensure we don't have character sequences that cause conflicts. I'm trying to avoid clashes with:

• Markdown
• Command-lines (bash, pwsh, or command)
• Comments in common programming languages

I think this proposal avoids all of those, but please help me make it so. Also, are there other clashes we should worry about? Where else will commit messages appear?

[JayBazuzi]

I thought maybe pound # rather than at @ might stand out a little better, and fit the vertical / horizontal lines motif. Did you consider that?

[JayBazuzi]

I will bring this new design to my teams to try out.

[arlobelshee]

I considered #, but was worried about it becoming a comment in a python context. I do think it stands out better and fits the theme well.

I also considered +, but that that is a markdown list. @ seems to only be a special char when followed by non whitespace.

I'm not sure which of these conflicts I should actually worry about.

As a python programmer, are you worried about the comment char overlap?

Arlo

On Sat, Jul 1, 2023, 10:51 Jay Bazuzi @.***> wrote:

I thought maybe pound # rather than at @ might stand out a little better, and fit the vertical / horizontal lines motif. Did you consider that?

— Reply to this email directly, view it on GitHub https://github.com/RefactoringCombos/ArlosCommitNotation/pull/43#issuecomment-1615947089, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAGCLHZ4LPNGQUA2BXTEPM3XOA2N3ANCNFSM6AAAAAAZ2FIEHI . You are receiving this because you authored the thread.Message ID: @.***>

[JayBazuzi]

I am not worried about programming languages' comment characters because this would always be in a quoted string. Is there an in-code use case I'm missing?

I am imagine interactive command line as being the primary use case, so I think about shell special characters first: backslash, backtick, ampersand, precent, dollar, etc. I think we're good there.

Markdown for writing docs about using the notation is a minor problem for #, like this:

R clean up the code and make it faster

But that is easily/appropriately addressed with a code block:

# R clean up the code and make it faster

[arlobelshee]

My concern with markdown is that many Web tools display all commit comments in a markdown context. They explicitly support the use of markdown in the comment. So it often would not appear inside a code fence.

[JayBazuzi]

Ah, yeah: if a merge commit is automatically populated with the list of commits in the source branch, that might be all formatted at markdown. Makes sense to avoid leading # for that reason.

[JayBazuzi]

I made a migration guide. https://github.com/RefactoringCombos/ArlosCommitNotation/blob/738f0b074b4ff2e8786ae9071688024c2baf141e/Migrating%20from%20V1%20to%20V2.md

[JayBazuzi]

A team I work with tried out ACN V2. Their feedback:

• they like intention all being uppercase, as it's less to think about.

• they like risk coming first, as it forces them to ask "how safe is this?" without getting distracted by intention. Previously they fell in to the trap of "this is a CI change, that's e" without noticing that it could break production.

[arlobelshee]

The proposal now uses the following risk codes:

Code	Meaning
.	Bug-for-bug compatible
^	No potentially-preventable regressions; may have regressed behaviors our customers use but we aren't aware of
!	The intended change was correct; may have impacted other functionality
@	No promises! It might work, or not.

[arlobelshee]

I considered other risk codes. As per discussion with Llewellyn and Jay, we wanted to get ! to be the second level, so that people learning to refactor feel a strong desire to keep it provably safe. I'm not sure whether ^ will elicit the same pain as ! does.

That said, the second level is the "best" level for features and bug fixes. So I want it to feel "nice" in that case. Also, most of the characters that are more explosive than ! have special meaning in either the shell or markdown.

Here are other things I considered. Do any of these stand out to you as good, or do you have an alternate suggestion?

Current	Possible Alternative (not proposed)
.	.
^	!
!	$ % & or /
@	@

$, %, and & are only OK in the shell because the will be followed by a space and included in some kind of quotes. Still, this seems very error-prone, so I am leaning against it.

The primary other alternative would be #, but that has meaning in markdown when used at the start of a line followed by space. That's the same reason we aren't using -, +, or * as risk codes.

[JayBazuzi]

I particularly dislike & because it's not symmetrical. / is asymmetric but less so; @ is close enough to symmetrical for me.

$ isn't as accessible on a lot of non-us keyboards, but programmers worldwide have figured out how to type this character thanks to Bash variables.

[JayBazuzi]

Did you consider |? Not sure where I'd put that.

I am suddenly reminded of ASCII wait animation, cycling |/-\.

[arlobelshee]

I considered pipe, but that also has a high chance of command line problem.

[JayBazuzi]

. / o / O / @ is an interesting visual sequence.

[arlobelshee]

Any votes between the following 2 options?

Option A	Option B	Meaning
.	.	Bug-for-bug compatible
^	o	No potentially-preventable regressions; may have regressed behaviors our customers use but we aren't aware of
!	O	The intended change was correct; may have impacted other functionality
@	@	No promises! It might work, or not.

[JayBazuzi]

Any votes between the following 2 options? ...

I asked around and got this reply:

I sort of like Option B. In terms of code review, @ notation would stand out far better in a sea of 0 or o than the other notations in Option A. Also I feel like Option B takes less of my memory capacity.

For me personally, having middle pair be similar to each other is quite a different cast than the low pair / high pair.

[arlobelshee]

I wrote a response and then deleted it. I'm trying to figure out a nuance of my intent.

I think it comes down to a question: when reviewing a sea of changes, do you want well-done feature changes to fade into the background or stand out?

This determines whether we want the visual filter to be between levels 1/2 or between 2/3. In other words, do we want to "see" levels 2, 3, 4 (ignore only level 1), or do we want to "see" levels 3, 4 (ignore levels 1 & 2)?

Interestingly, using the o for level 2 gives us both options, depending on what character we use for level 3. Here are 3 options. I feel that Option A brings the top 3 levels into the visual foreground, while Options B & C only bring the top 2 levels into the visual foreground.

So should level 2 be in the foreground or background? And which option best gives that result?

Option A	Option B	Option C	Meaning
.	.	.	Bug-for-bug compatible
o	o	o	No potentially-preventable regressions; may have regressed behaviors our customers use but we aren't aware of
O	!	%	The intended change was correct; may have impacted other functionality
@	@	@	No promises! It might work, or not.

[JayBazuzi]

I want all of the above! But if I had to choose, I would pick the boundary between 2 and 3.

[JayBazuzi]

I want both scanning and discomfort, and which levels I care about varies by context.

As a code reviewer looking at a PR I want to quickly identify level 3 and 4 commits so I can scrutinize them for mistakes or give feedback to the developer about reworking the change (both 4->3 rework and 3->2/1 rework are improvements I want to encourage).

As a spelunker trying to figure out why the last release broke production I want to find all level 2, 3, and 4 commits because that's where the risk is.

As a release engineer I want to find the first 2/3/4 commit and maybe ship everything before that point in one go with minimal ceremony, and then I can follow up with more ceremony to ship the rest.

When committing a change I want us to feel discomfort when we're using a higher risk level than we need to.

• We can go from 4 to 3 by breaking up changes and including tests. We should almost always do that.
• Building out the test coverage (and modularity) to go from 3 to 2 is a big job that doesn't easily slip into the current User Story but if the test coverage is in place then we should be able to hit 2 most of the time.
• 1 is generally only possible if we're working in a language + tooling that supports it. Switching to a proper language will not fit in the current User Story. If we're at 2 we have probably done as well as we can today.

So there are cases where 1/2 is the right boundary, where 2/3 is the right boundary, and 3/4 is the right boundary.

While writing release notes I want to see all the F and B changes.

I see we're using numbers in this discussion. Last week a dev on one of my teams said he wants the risk level to be digits 1..9, instead of inventing new symbols. Obviously, that loses scanability but I wanted to pass it on.

This reminds me that I wish we had proper tooling. I wish that Git had a general-purpose commit metadata system beyond author, time, tag, signature - I want to add a Risk tag and an Intent tag and then I want a log view that I can filter and highlight. Maybe one day.

[JayBazuzi]

Discussed with Emily Bache this morning and she said that o / O look too much alike to discern, even when you're looking closely.

[JayBazuzi]

We've been beta testing V2 for a while. We're generally pretty happy with it.

No one likes the idea of (o vs. O) or (O vs 0) as they look a lot like each other in some fonts. (o vs 0) might be OK, but we don't love it.

[arlobelshee]

So Jay, what is your preferred indication for each risk level?

I've been doing ./o/O/@, but am very happy to adopt another alternative.

Arlo

On Mon, Oct 16, 2023, 16:41 Jay Bazuzi @.***> wrote:

We've been beta testing V2 for a while. We're generally pretty happy with it.

No one likes the idea of (o vs. O) or (O vs 0) as they look a lot like each other in some fonts. (o vs 0) might be OK, but we don't love it.

— Reply to this email directly, view it on GitHub https://github.com/RefactoringCombos/ArlosCommitNotation/pull/43#issuecomment-1765237798, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAGCLH3N43VKQSKTFNFEIZLX7WLWVAVCNFSM6AAAAAAZ2FIEHKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTONRVGIZTONZZHA . You are receiving this because you authored the thread.Message ID: @.***>

[MichaelRWolf]

Have you looked at any of the (decades-old by now) ASCII art generators, or translators? They mostly map to lines and angles, but some of the more interesting ones had grey-scale mappings that may help with the back-of-the-retina precessing. But I also bet that they are not portable.

BTW... I have been playing with a message-generating script (tentatively called RIMC - Risk/Intent Commit Message) that hard-codes ./^/!/@, but I had intended to have that mapping pulled from a config file, so everyone could create their own mapping (and thus defeat one of the intents of having a "standard").

Once I've got the 'encoder' working, I had toyed around with creating a 'decoder' that would translate "standard" messages by adding color. The ANSI escape sequences are at least "standard" and implemented on terminals (and emulators) for about 50 years.

[MichaelRWolf]

I'm going to propose using it in some public mobs that I participate in.

I've creating messages like this...

$ (./ricm.py --risk risky --intent feature 'Add --HELP_FOR_RICM to display risk and intent options'; echo; cat contributers) | pbcopy; pbpaste
! f Add --HELP_FOR_RICM to display risk and intent options

Manny
Moe
Jack
$

Then either (1) paste into commit message of GUI (IntelliJ, GitKraken, etc...) or (2) recall this line from history in a shell

$ git commit -m "$(pbpaste)"
$

[JayBazuzi]

So Jay, what is your preferred indication for each risk level?

I have been trying both and I don't have a definitive answer. Preference feelings that come up for me are mild and they don't clump up around one option.

If you said that the only way that V2 could ship is if Jay made a choice, I would pick ./o/O/@.

[JayBazuzi]

I've continued to use ./o/O/@ and today got some feedback that o r looks too much like the English word "or".

However, this came from someone who generally doesn't use ACN except for F/B/R**, so I don't know if they're in a good position to judge the system.

I'm now experimenting with surround with brackets, e.g. [o r] to see how that feels.

[JayBazuzi]

We could offer two options. "Experiment with these with your team and choose the one that suits people better."

Tag	Risk
.	Known Safe
o/^	Addresses all known risks
O/!	Some known risks remain unverified
@	No risk attestation

[JayBazuzi]

- looks like a very natural punctuation in certain contexts, which detracts from its effectiveness as a commit notation. For example here it looks like it just separates the commit ID from its description.