search

RefactoringCombos / ArlosCommitNotation

A notation for small commits messages that show the risk involved in each step
310 stars 30 forks source link

Multiple spaces get lost in many UIs #26

Closed JayBazuzi closed 2 years ago

JayBazuzi commented 3 years ago

We currently use three spaces for safer commits (r Extract Method) so that they align well with unsafe commits (R!! Cleaned up the core logic) but that only works with fixed-width display. Many UIs merge those spaces, like this in GitHub:

image

JayBazuzi commented 3 years ago

On one project we're using r -. Maybe something like that would work?

Maybe r..?

arlobelshee commented 3 years ago

I personally prefer whitespace over .. as it makes the !! and ** stand out. Your proposal for - meets that well (I think). An example would be:

r - lorem ipsum
F - lorem ipsum
t - lorem ipsum
r - lorem ipsum
F!! lorem ipsum
r - lorem ipsum
R - lorem ipsum
B** lorem ipsum
F!! lorem ipsum
d - lorem ipsum
arlobelshee commented 3 years ago

I'd love to hear thoughts from @isidore, @mscottford, or others on this proposal.

JayBazuzi commented 3 years ago

Just for comparison:

r.. lorem ipsum
F.. lorem ipsum
t.. lorem ipsum
r.. lorem ipsum
F!! lorem ipsum
r.. lorem ipsum
R.. lorem ipsum
B** lorem ipsum
F!! lorem ipsum
d.. lorem ipsum
JayBazuzi commented 3 years ago

And one more:

r__ lorem ipsum
F__ lorem ipsum
t__ lorem ipsum
r__ lorem ipsum
F!! lorem ipsum
r__ lorem ipsum
R__ lorem ipsum
B** lorem ipsum
F!! lorem ipsum
d__ lorem ipsum
mscottford commented 3 years ago

My initial reaction is to wonder about the importance of the extra spaces. It appears that they are primarily needed to help the eye notice when !! is used. But I wonder if there might be another approach that could achieve the same goal.

!F! and .r. might be a good alternative. Because then instead of the .. or __ being used as padding characters, they are being used as delimeters. And then the delimiter conveys meaning in addition to the single character that it wraps.

.r. lorem ipsum
.F. lorem ipsum
.t. lorem ipsum
.r. lorem ipsum
!F! lorem ipsum
.r. lorem ipsum
.R. lorem ipsum
*B* lorem ipsum
!F! lorem ipsum
.d. lorem ipsum

I'm curious about y'all's thoughts on that.

arlobelshee commented 2 years ago

Hm. I'm losing glance-ability with any of the options that use periods. My number 1 priority with this encoding is for someone to quickly glance down the column and, without reading, see the high-risk commits. I really want ** and !! to stand out. I'd like R to stand out some from r, but that is less important.

The underscores work a little better than periods for me at a glace, though still not as good as spaces (even with the hyphen).

arlobelshee commented 2 years ago

!F! and .r. might be a good alternative. Because then instead of the .. or __ being used as padding characters, they are being used as delimeters. And then the delimiter conveys meaning in addition to the single character that it wraps.

I'm curious about y'all's thoughts on that.

What advantage do you see to having these as delimiters? Personally I don't get a psychological difference between delimiter and trailing marker. What are you noticing that I miss?

mscottford commented 2 years ago

My initial thought along those lines was that if there were start and stop delimiters, instead of fixed width/padding, then the mechanism could employ longer terms instead of just single characters, and that this might increase understanding amongst other teams. Perhaps something similar to Gitmoji, but instead of relying on the emoji names, aliases are created.

I trimmed that back to the proposal that I sent in because I suspected that would be more drastic a change than was requested. That original idea looked something like this:

:safe: :refactor: lorem ipsum
:validated: :feature: lorem ipsum
:safe: :test: lorem ipsum
:safe: :refactor: lorem ipsum
:risky: :feature: lorem ipsum
:safe: :refactor: lorem ipsum
:risky: :refactor: lorem ipsum
:broken: :bugfix: lorem ipsum
:risky: :feature: lorem ipsum
:safe: :docs: lorem ipsum

Which I suspected would not meet the goals that you all have. However, this approach allows someone to very quickly scan the list for :safe:, :validated:, :risky: or :broken: by placing that detail first.

I'm noticing that this preference of having a start and stop character stems from me not being a very big fan of meaningful whitespace. In addition to GitHub not rendering the extra spaces, I notice that I often forget to actually type them out. :) It's completely possible that this approach is incompatible with the goals of this effort. :)

I'm also noticing that the suggestion that I've made above is influenced by a desire to avoid a single value having two different meanings (f and F** communicates both risk and change-type) and a desire to avoid the introduction of more initialisms since those tend to lead to "what does that mean" questions.

arlobelshee commented 2 years ago

I'm going to close this with the adoption of - as the separator instead of .

I see the value of your proposal, Scott, but yeah, I don't find it to meet the goals of this notation. I'm explicitly looking for a columnar format, as that makes vertical scanning easy. Gitmoji would account for that, as long as the tooling supported it (and there was decent auto-complete when writing the commit message). I'd take your proposal over mine if those were both true!