diff --git a/README.md b/README.md index 037d339..9a623bd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Risk-Aware Commit Notation -

(aka Arlo's Commit Notation)

- 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? @@ -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` — just the pull request commit summaries to understand the history of changes for a release. +4. Reading `main` — 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: @@ -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: | -| `! 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: | +| `💣 F` | Change includes unit tests for new behavior. | +| `💥 F` | No automatic tests, or unfinished implementation. | ### Bugfix @@ -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: | -| `! 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: | +| `💣 B` | Change includes unit tests for new behavior. | +| `💥 B` | No automatic tests, or unfinished implementation. | ### Refactoring or Remodeling @@ -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: | -| `^ r` | Test-supported Procedural Refactoring[3] | -| `! 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: | +| `✅ r` | Test-supported Procedural Refactoring[3] | +| `💣 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 @@ -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 diff --git a/v1/Extension Intentions.md b/v1/Extension Intentions.md deleted file mode 100644 index aa362ec..0000000 --- a/v1/Extension Intentions.md +++ /dev/null @@ -1,16 +0,0 @@ -## Extension Intentions - -Each project can define a set of extension intentions. Each project should define which extension codes it uses. It is up to each project to define the approaches for each of the 4 risk levels. - -These are some common intentions, each used in several projects. Each also lists alternatives used in projects that don't use the code. - -| Prefix | Name | Intention | Alternatives | -| --- | --- | --- | --- | -| M | Merge | Merge branches | Use `F`, `B`, or `R`, based on the main intention of the branch, with risk level based on maximum for any individual commit in the branch. Optionally leave blank for merge from main to a feature branch. | -| T | Test-only | Alter automated tests without altering functionality. May include code-generating code that just throws a `NotImplementedException` or similar approaches. | Use `f` or `b`, depending on which kind of work this test is going to validate. Use `r` if this is a refactoring purely within test code. It is a lower-case letter unless you also change product code. | -| E | Environment | Environment (non-code) changes that affect development setup, and other tooling changes that don't affect program behavior (e.g. linting) | Consider the environment to be a product where the users are team members, and code it accordingly. | -| A | Auto | Automatic formatting, code generation, or similar tasks. | Use the intention that matches the reason you are performing the action, almost-certainly as a lower-case level of risk. For example, code cleanup would be `r`, and generating code to make a test for a new feature compile would be `t` or `f`. | -| C | Comment | Changes comments only. Does not include comments that are visible to doc-generation tools. | Use `D`. | -| P | Process | Changes some team process or working agreement. | Any of: | -| S | Spec | Changes the spec or design. Used when team does formal specs or design reviews and keeps all such documents in the main product source, perhaps in the product code itself. | Any of: | -| * | Unknown / multiple | Made a bunch of changes and are just getting it checked in. No real way to validate safety, and may not even compile. Usually used at the highest risk level (`***`). | Don't allow this. Require each commit to do exactly one intention and document itself accordingly. | diff --git a/v1/Learning Path.md b/v1/Learning Path.md deleted file mode 100644 index cd6a74e..0000000 --- a/v1/Learning Path.md +++ /dev/null @@ -1,194 +0,0 @@ -# Incremental learning and adoption path - -For a team that has never tried disciplined refactoring there is a steep learning curve to adopt this system. - -To reduce that challenge, here we describe the tiniest increments to learning and adopting Arlo's Commit Notation. This way you can get used to one idea before getting overwhelmed by the next idea, and get a quicker return on the learning investment. - -Expect some disagreement and confusion in the team throughout this process, as people shift their thinking. As you find agreement, write down your new norms in your team agreements. Give feedback to Arlo's Commit Notation about how it could be been clearer for you. - -Hint: this all goes much more smoothly with Mob/Ensemble Programming ([Promiscuious Pairing](https://csis.pace.edu/~grossman/dcs/XR4-PromiscuousPairing.pdf) is also pretty good) to share knowledge, increase "insights per hour", and shift norms more quickly. - -Hint: a good technical coach can be a huge help for your team to learn and adopt these skills. - -## 1. Working in a short-lived branch - -While Trunk-Based Development directly in `main` is good for keeping everyone's work in sync and reducing merges, a short-lived branch lets you document the steps in your development process, telling a story to reviewers and future readers of your changes. 1 day is a good maximum lifetime for a branch (shorter is better), enabling incremental commits without incurring most of the risks of long-lived branches. - -If you're in a context where code review is part of the flow of work, teach reviewers how to look at the individual branch commits as an option that may be easier than viewing the whole change all at once. Mention this option in the description of the final Merge Request, e.g. "see the individual commits in the branch for more details". - -Depending on your VCS solution, you will need to find a way to keep these details visible after merging to main, such as `rebase` + `merge --no-ff`. - -### Example commit history - -``` -Implement automatic log-off -Clean up the login module -``` - -One benefit of working this way is that it's easier to provide rich, detailed descriptions for the smaller increments in a branch than for the whole ball of changes. - -In legacy code, we often see code that looks "weird" but we don't know if was deliberately made this way for a subtle reason, or the dev just didn't get around to cleaning it up. Incremental work with rich descriptions can be really helpful for future readers trying to understand why the code ended up like this. - -## 2. Tag refactorings with `R**` - -If a change contains only refactoring, indicate that by prefixing the change description with `R** `. - -The refactoring need not be especially disciplined. This is just about separating refactoring from non-refactoring in your commit history. - -Folks on your team probably have [multiple working defintions of refactoring](https://jay.bazuzi.com/DefinitionsOfRefactoring/), and this is an invitation to examine those defintions and find a shared understanding. - -Refactorings often have a large diff even though they don't change behavior and are out of proportion with the conceptual size of the change. For example "rename A to B" is one small idea but every line that references `A` will be affected. If combined with deliberate behavior changes that will make reading the total diff difficult. Separating refactorings into their own commits will make code review easier. You should be able to scan the commit history and easily see which are refactorings and which are not. - -### Example commit history - -``` -Implement automatic log-off -R** Remove duplication in login module -R** Rename a bunch of stuff for clarity -``` - -For a future reader of the code trying to understand how the code got this way, if you're looking for a deliberate behavior change you know you can ignore `R**` changes; if you see a behavior change in a commit marked `R**` you know it was accidental. - -## 3. Pick up easy wins - -Once the team has learned the above practices, the following tags are easy to adopt. - -- `t` for test-only changes -- `a` for auto-formatting -- `R!!` for named refactorings - -### Example commit history - -``` -t - fill in missing tests for existing login code -R!! Extract Method -a - autoformat with prettier -``` - -If you haven't already, this is a good time to add automatic code formatting to your CI checks, and bring all existing code in to compliance with that formatting. - -## 4. Tag Features and Bug Fixes with `F**` and `B**`. - -Make a team agreement to categorize commits and tag with one of the above. - -It may be a good idea to allow `***` (uncategorized) in certain contexts. One example is "checkpointing", where you have some in-progress experimental changes on one machine and want to try them on another machine or share them with a coworker. - -At this point you can considering adopting a regex check to ensure that all commits are tagged. See https://github.com/RefactoringCombos/ArlosCommitNotation/issues/29. - -### Example commit history - -``` -F** Implement automatic log-off -R** Remove duplication in login module -R** Rename a bunch of stuff for clarity -``` - -## 5. Refactor to prepare code for behavior change - -> Make the change easy (warning: this may be hard), then make the easy change. -- Kent Beck - -For each feature or bug fix, practice replacing "how can I get this behavior change to fit in to the current design?" with "what design would make it really easy to implement this feature in a natural way?" and "what small refactorings would it take to get from here to there?". You're looking for `R!!`-style, single named refactorings. Commit histories will start to look like a series of refactorings followed by a deliberate behavior change. - -### Example commit history - -``` -F** Automatically log-off when idle -R!! Introduce parameter -R!! Import nodatime -R!! Merge duplicate code -R!! Extract Method -``` - -This also gives you the option of merging to `main` before your feature or bug fix is complete. For example, on one day you might do a bunch of `R!!` refactorings, get them approved and merged quickly thanks to the above practices, then continue towards your feature or bug fix the next day. - -## 6. Safe Refactoring - -Can your IDE safely execute a refactoring? If so, you can use `r`. This is great for code review, as reviewers can now skim some changes instead of examining them carefully for correctness issues. This means means you can get your code review results back even more quickly. - -Where your IDE is unable to provide the required level of safety, look at [recipe-based refactorings](https://github.com/InnovatingTeams/provable-refactorings). - -Once your team has gotten comfortable with `r`, consider changing your code review and delivery protocols to allow lower-case (safe) changes to skip some/most/all of those requirements. This has several benefits, including creating an incentive for developers to work in this safe way. - -Note that this level of safety is hard to get in dynamic languages. If that's your context, you may need to instead make the investment in comprehensive test coverage to unlock `R`. - -### Example commit history - -``` -r - Merge identical methods -r - Rename local variables -r - Extract Method -``` - -## 7. Small features and bug fixes - -Once you get in familiar with refactoring in preparation for a feature, you can further reduce risk by refactoring to the point where a feature or bug fix only requires a small code change. That unlocks `F` and `B`. - -### Example commit history - -``` - -F - Automatically log-off when idle -r - -t - -r - -r - -R!! -r - -t - -r - -R!! -r - Merge duplicate code -r - Extract Method -``` - -# TDD with ACN - -In a strict Test-Driven Development cycle almost all commits are either a new test or a refactoring. When using ACN: - -1. Write a new failing test (Red) -1. Make it pass (Green) -1. Commit with `F - `. -1. Refactor. -1. Commit each refactoring. - - If the refactoring is executed with a known safe tool or recipe, use `r`. - - If this is new, un-called code and you have been doing TDD since the start, you probably have the test coverage to use `R`. - - If you are "triangulating", converting special-case code to a generalized algorithm, use may need to use `R**`. - -### Example commit history - -``` -R - replace algorithm -F - FizzBuzz of 3 is "Fizz" -F - FizzBuzz of 2 is "2" -r - rename parameter -F - FizzBuzz of 1 is "1" -``` - -# Alternatives - -## All-at-once - -If working as an ensemble with a highly skilled and capable technical coach, then bring in all of the practices at once and let the coach guide the team to use them as the work requires. - -## Categorize first - -This approach scales up to larger multi-team organizations where there's not enough hands-on coaching capacity to do it all at once. - -Make the requirement that all changes must be categorized in to one of Feature (`F**`), Bug Fix (`B**`), or Refactoring (`R**`) and tagged as such. No other change to developer behavior is required. `***` is an escape valve, e.g. for checkpointing work to move it to another machine. - -If a change contains both feature and bug fix work, use `F**`. - -If a change contains both refactoring and non-refactoring work, use the appropriate non-refactoring tag. - -Invite developers/pairs/ensembles to use other risk and intent annotations as they see fit, and praise when that is done, but don't require it at first. - -Roll out in these increments: - -1. Categorize (`F**` / `B**` / `R**` / `***`) -2. Corral Risk (`F!!`, `B!!` / `R!!`) -3. Validated (`F` / `B` / `R`) -4. Safe (`f` / `b` / `r`) - -## Safety First - -Start by introducing `r` an suggesting incremental work in a branch. Allow these kinds of changes a fast track through review and release. Build from there. diff --git a/v1/index.md b/v1/index.md deleted file mode 100644 index d7ddaf0..0000000 --- a/v1/index.md +++ /dev/null @@ -1,167 +0,0 @@ -# Arlo's Commit Notation - -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? -2. What was the intention? When the original author changed the code, what was s/he attempting to accomplish? - -This information is conveyed in the first 3 characters of the commit summary line. That way a receiving developer can quickly scan the commit log in order to determine risk and intent for any incoming change set. - -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` — just the pull request commit summaries to understand the history of changes for a release. - -## The Four Risk Levels - -| Risk Level | Code | Example | Meaning | -| --- | --- | --- | --- | -| **Known safe** | lowercase letter | `r - Extract method Applesauce` | Addresses all known and unknown risks. | -| **Validated** | uppercase letter | `R - Extract method Applesauce` | Addresses all known risks. | -| **Risky** | uppercase followed by 2 bangs | `R!! Extract method Applesauce` | Known risks remain unverified. | -| **(Probably) Broken** | uppercase followed by 2 stars | `R** Start extracting method with no name` | No risk attestation. | - -* **Known safe:** Developer performed the task in a way that prevents the potential risks, even for situations that developer is not aware of. -* **Validated:** Developer performed the task in some way that includes validation for all risks the developer thought of. The most common technique is developer-written automated tests. -* **Risky:** Developer is aware of risks and attempted to mitigate them as much as possible, but there is no formal verification. Commonly this includes a manual change that the developer could not fully verify. -* **Broken:** Either known to be broken, or developer couldn't even check to see if it works. May not compile. Used when the developer cannot see the results of the work without checking in, or as a savepoint when the developer is about to switch tasks or direction. - -## Core Intentions - -These developer intentions exist on every project. They are always allowed in commits that use this notation. - -Each intention can appear at any of the 4 risk levels. Each intention's full details section includes the potential risks inherent in that kind of change, as well as common approaches to attain each risk level. - -| Prefix | Name | Intention | -| --- | --- | --- | -| F | Feature | Change or extend one aspect of program behavior without altering others. | -| B | Bugfix | Repair one existing, undesirable program behavior without altering any others. | -| R | Refactoring | Change implementation without changing program behavior. | -| D | Documentation | Change something which communicates to team members and does not impact program behavior. | - -### Feature - -**Known Risks** - -* May alter unrelated feature (spooky action at a distance). -* 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 | -| --- | --- | -| `f - ` | None known | -| `F - ` | Meets all of:
  • Change is <= 8 LoC[5]
  • Feature was fully unit tested prior to this change.
  • Change includes new or changed unit tests to match intended behavior alteration.
| -| `F!!` | Change includes unit tests for new behavior. | -| `F**` | No automatic tests, or unfinished implementation. | - -### Bugfix - -A bugfix is a lot like a feature. However, the intention is to change an undesired — and usually unintentional — behavior of the current system. The risk profile is similar but the intention is different, so there are often more operational risks. - -**Known Risks** - -* Intended change may have unintended consequences in the market. For example, customers may be depending on the bug. -* May alter unrelated feature (spooky action at a distance). -* 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 | -| --- | --- | -| `b - ` | None known | -| `B - ` | Meets all of:
  • Reviewed current and new behavior with customer representative.
  • Change is <= 8 LoC[5]
  • Bug's original (buggy) behavior was captured in a unit test prior to this change.
  • Change includes 1 changed unit test, matching intended behavior alteration.
| -| `B!!` | Change includes unit tests for new behavior. | -| `B**` | No automatic tests, or unfinished implementation. | - -### Refactoring or Remodeling - -A Refactoring or Remodeling intends to alter the program in some way without changing any behavior. The risk levels indicate the probability of the commit living up to that intention, based on how the code change was executed. - -**Known Risks** - -* May cause a bug. -* May fix a bug. -* May change a behavior in a way that doesn't impact a user. -* May force a test update. - -| Code | Known Approaches | -| --- | --- | -| `r - ` | One of:
  • Provable refactoring[2]
  • Test-supported Procedural Refactoring[3] entirely within test code
| -| `R - ` | Test-supported Procedural Refactoring[3] | -| `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 - -Changes that don't impact the code, but do change documentation around the code. Note that this does not include end-user documentation[1]. - -**Known Risks** - -* May mislead future developers. -* May mislead other stakeholders. -* May alter team processes in ways that have unintended consequences. - -| Code | Known Approaches | -| --- | --- | -| `d - ` | Developer-visible documentation, not in a source file, or verified to generate byte-identical compilation. | -| `D - ` | Dev-impacting only, but changes compilation or process. E.g., changing text on a dev-only screen, or changes code-review checklist. | -| `D!!` | Alters an important process. | -| `D**` | Trying out a process change that is intended to gain info, not to work. | - -## Extension Intentions - -The basic intention annotations are comprehensive to describe any kind of change, but it may be useful to extend the notation to your project to provide additional detail that is useful in your context. Read more about [Extension Intensions](Extension%20Intentions.md). - -# Provable Refactorings -[2]:#provable-refactorings - -If you can get a series of commits that is all lowercase commits, you can deploy without the need for Regression Testing, or lengthy conversations about accepting the pull request to trunk. - -A provable refactoring requires a burden of proof. The main methods of proof are -* automated refactoring via tool, with knowledge of tool bugs. -* Scripted manual refactoring, using the compiler to verify each step. [Recipes Here](https://github.com/InnovatingTeams/provable-refactorings) - -With discipline these can prove bug-for-bug compatibility. They demonstrate safety for unknown bugs, even guaranteeing that you do not accidentally fix a bug you don't know exists (but your customers may be depending on). - -All of these recipes use static analysis to demonstrate safety. As such, they work equally well on code that lacks tests. They can be a good way to make code testable. Their downside is that they are language-specific. - -# Test-supported Procedural Refactorings -[3]:#test-supported-procedural-refactorings - -These are refactorings with a lower standard of proof: -1. Commit contains only a single refactoring. -2. Refactoring is named and published (e.g., in [Fowler's refactoring catalog](https://refactoring.com/catalog/)). -3. Either: - 1. Your entire product is very highly tested, or - 2. you are working on new code that is not yet called. -4. You followed the published steps, including running full-suite test runs when indicated. - -Note that this can not prove bug-for-bug compatibility. It can only demonstrate that you didn't cause any problems that have been thought of before; it does not demonstrate safety for novel bugs. - -Requirement 3 is there because many refactorings can have non-local effects. It is not sufficient to have great tests on the code you are changing. You also need great tests on the code that you are not intending to change, to demonstrate that you didn't. Therefore, until your entire codebase is very highly tested, you will only be able to use the `R` commit designation on new code that is uncalled by your product. - -# End-User Documentation -[1]:#end-user-documentation - -End user documentation is a feature, bugfix, or refactoring, depending on its nature. Use those codes (including levels of risk) accordingly. - -# Small Features and Bug Fixes -[4]:#small-features-and-bug-fixes - -Features and bug fixes intentionally change behavior. This makes them much riskier than refactorings. It is not possible to prove that they have only the intended effect. However, small changes are much lower risk for three reasons: - -1. It's only possible when the code is well-organized already. -2. It's easy to see the possible side effects of small chunks of code. -3. It's easy to code review, so you are likely to get good reviews. - -Therefore, we treat any feature or bug fix as high risk if it changes more than 8 lines of code in one commit. This includes test changes. - -One good approach to enable small features is to refactor until the feature change is easy, then add it. Then add the feature one piece at a time, with a test for each. - -# Living Documentation - -We invite you to submit pull requests to help evolve this notation and methodology. - -LoC: Lines of Code - -[5]:#lines-of-code