Skip to content

feat: Use emoji for risk to improve glance focus #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: Use emoji for risk to improve glance focus #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
00b467e
! f We no longer need to explicitly mention Arlo. People coming here …
arlobelshee Aug 6, 2025
f1bef03
! F Can we remove v1? Move everything on to v2.
arlobelshee Aug 6, 2025
cae695f
^ f Link to movement-oriented branches.
arlobelshee Aug 6, 2025
7dab60a
^ f Clarify risk description.
arlobelshee Aug 6, 2025
269e2c9
💣 F Use emoji for risk codes!
arlobelshee Aug 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 26 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Risk-Aware Commit Notation

<p style="font-size: 80%;margin: -1.6em 0 3em;">(aka Arlo's Commit Notation)</p>

This commit notation allows developers to convey 2 critical pieces of metadata about each commit:

1. How risky is it? What has the original author done to mitigate risk?
Expand All @@ -13,18 +11,18 @@ This is particularly useful when:

1. As a reviewer, deciding whether to approve a pull request
2. As a developer, getting your pull request approved faster and more easily
4. Reading `main` &mdash; just the pull request commit summaries to understand the history of changes for a release.
4. Reading `main` &mdash; use [Movement-oriented branches](Movement%20Branches.md) and read just the merge commits.

## The Four Risk Levels

We divide all behaviors of the system into 3 sets. The change is intended to alter the *Intended Change* while not altering any of the *Invariants*. The *Risk Levels* are based on correctness guarantees: which invariants can this commit guarantee did not change, and can this commit guarantee that it changed the intended change in the way the authors intended?
We divide all behaviors of the system into 3 sets (intended change, known invariants, and unknown invariants). The change is intended to alter the *Intended Change* while not altering any of the *Invariants*. The *Risk Levels* are based on correctness guarantees: which invariants can this commit guarantee did not change, and can this commit guarantee that it made the intended change in the way the authors intended?

| Risk Level | Code | Example | Meaning | Correctness Guarantees |
|-----------------------|------|--------------------------------------------|----------------------------------------|-------------------------------------------------------|
| **(Proven) Safe** | `.` | `. r Extract method` | Addresses all known and unknown risks. | Intended Change, Known Invariants, Unknown Invariants |
| **Validated** | `^` | `^ r Extract method` | Addresses all known risks. | Intended Change, Known Invariants |
| **Risky** | `!` | `! r Extract method` | Some known risks remain unverified. | Intended Change |
| **(Probably) Broken** | `@` | `@ r Start extracting method with no name` | No risk attestation. | |
| **(Proven) Safe** | `.` or 💚 | `💚 r Extract method` | Addresses all known and unknown risks. | Intended Change, Known Invariants, Unknown Invariants |
| **Validated** | `^` or ✅ | `✅ r Extract method` | Addresses all known risks. | Intended Change, Known Invariants |
| **Risky** | `!` or 💣 | `💣 r Extract method` | Some known risks remain unverified. | Intended Change |
| **(Probably) Broken** | `@` or 💥 | `💥 r Start extracting method with no name` | No risk attestation. | |

Behavior categories:

Expand Down Expand Up @@ -69,12 +67,12 @@ Each intention may be expressed in UPPERCASE or lowercase. The team uses this di
* May alter a piece of this feature that you intended to remain unchanged.
* May implement the intended change in a way different than intended.

| Code | Known Approaches |
| Encoding | Known Approaches |
|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `. F` | Meets all criteria for `^ F` and developers are the only users of the feature. For example, extends build tooling for your own build or adds debug logging. |
| `^ F` | Meets all of:<ul><li>Change is <= 8 <abbr title="lines of code">LoC</abbr><sup>[5]</sup></li><li>Feature was fully unit tested prior to this change.</li><li>Change includes new or changed unit tests to match intended behavior alteration.</li></ul> |
| `! F` | Change includes unit tests for new behavior. |
| `@ F` | No automatic tests, or unfinished implementation. |
| `💚 F` | Meets all criteria for `✅ F` and developers are the only users of the feature. For example, extends build tooling for your own build or adds debug logging. |
| `✅ F` | Meets all of:<ul><li>Change is <= 8 <abbr title="lines of code">LoC</abbr><sup>[5]</sup></li><li>Feature was fully unit tested prior to this change.</li><li>Change includes new or changed unit tests to match intended behavior alteration.</li></ul> |
| `💣 F` | Change includes unit tests for new behavior. |
| `💥 F` | No automatic tests, or unfinished implementation. |

### Bugfix

Expand All @@ -89,12 +87,12 @@ A bugfix is a lot like a feature. However, the intention is to change an undesir
* May alter a piece of this feature that you intended to remain unchanged.
* May implement the intended change in a way different than intended.

| Code | Known Approaches |
| Encoding | Known Approaches |
|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `. B` | Meets all criteria for `^ B` and developers are the only users of the changed functionality. For example, fixes build tooling for your own build or corrects debug logging format. |
| `^ B` | Meets all of:<ul><li>Reviewed current and new behavior with customer representative.</li><li>Change is <= 8 <abbr title="lines of code">LoC</abbr><sup>[5]</sup></li><li>Bug's original (buggy) behavior was captured in a unit test prior to this change.</li><li>Change includes 1 changed unit test, matching intended behavior alteration.</li></ul> |
| `! B` | Change includes unit tests for new behavior. |
| `@ B` | No automatic tests, or unfinished implementation. |
| `💚 B` | Meets all criteria for `✅ B` and developers are the only users of the changed functionality. For example, fixes build tooling for your own build or corrects debug logging format. |
| `✅ B` | Meets all of:<ul><li>Reviewed current and new behavior with customer representative.</li><li>Change is <= 8 <abbr title="lines of code">LoC</abbr><sup>[5]</sup></li><li>Bug's original (buggy) behavior was captured in a unit test prior to this change.</li><li>Change includes 1 changed unit test, matching intended behavior alteration.</li></ul> |
| `💣 B` | Change includes unit tests for new behavior. |
| `💥 B` | No automatic tests, or unfinished implementation. |

### Refactoring or Remodeling

Expand All @@ -109,12 +107,12 @@ A Refactoring or Remodeling intends to alter the program in some way without cha
* May change a behavior in a way that doesn't impact a user.
* May force a test update.

| Code | Known Approaches |
| Encoding | Known Approaches |
|-------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `. r` | One of: <ul><li>Provable refactoring<sup>[2]</sup></li><li>Test-supported Procedural Refactoring<sup>[3]</sup> entirely within test code</li></ul> |
| `^ r` | Test-supported Procedural Refactoring<sup>[3]</sup> |
| `! r` | Identified single, named refactoring, but executed by editing code or without whole-project test coverage. |
| `@ r` | Remodeled by editing code, even in small chunks. |
| `💚 r` | One of: <ul><li>Provable refactoring<sup>[2]</sup></li><li>Test-supported Procedural Refactoring<sup>[3]</sup> entirely within test code</li></ul> |
| `✅ r` | Test-supported Procedural Refactoring<sup>[3]</sup> |
| `💣 r` | Identified single, named refactoring, but executed by editing code or without whole-project test coverage. |
| `💥 r` | Remodeled by editing code, even in small chunks. |

### Documentation

Expand All @@ -128,12 +126,12 @@ Changes that don't impact the code, but do change documentation around the code.
* May mislead other stakeholders.
* May alter team processes in ways that have unintended consequences.

| Code | Known Approaches in source files | Known Approaches in other files |
| Encoding | Known Approaches in source files | Known Approaches in other files |
|-------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| `. d` | Developer-visible documentation verified to generate byte-identical compilation. | Any developer-visible documentation that does not change a process |
| `^ d` | Verified by running tests, or things like changing text on a dev-only screen. | Dev-impacting only, but changes compilation or process. E.g. changes code-review checklist. |
| `! d` | Verified only by compiling and launching the application. | Alters an important process. |
| `@ d` | Not verified. | Trying out a process change that is intended to gain info, not to necessarily work. |
| `💚 d` | Developer-visible documentation verified to generate byte-identical compilation. | Any developer-visible documentation that does not change a process |
| `✅ d` | Verified by running tests, or things like changing text on a dev-only screen. | Dev-impacting only, but changes compilation or process. E.g. changes code-review checklist. |
| `💣 d` | Verified only by compiling and launching the application. | Alters an important process. |
| `💥 d` | Not verified. | Trying out a process change that is intended to gain info, not to necessarily work. |

## Extension Intentions

Expand Down
16 changes: 0 additions & 16 deletions v1/Extension Intentions.md
View file
Open in desktop

This file was deleted.

Loading