[Feature]: Generate a quick-retro.md using tcr stats

[philou]

Contact Details

[email protected]

Feature Request

⚠️ OUTDATED:

We currently have a --commit-failures option, that adds complexity and creates parasite 'file updates' that conflict with the programming flow. We could fix these file-update parasites, but why invest in a feature if it is not useful?

We originally built the --commit-failures option to improve the quick retros at the end of Katas, but we currently don't leverage that.

Before fixing the --commit-failures option, we want to make sure it is useful. We thought of this simple experiment to validate its value.

We since replaced the commit-failure option by the introspective variant. It's already way easier to implement and support.
Yet the generation of a custom quick-retro based on the commit history remains an interesting experiment.

Feature Description

We will start by generating a quick-retro question showing the difference in size of failures and successes.

To do that, we will:

• Add a stat for the average size of failures and successes
• Add a command 'retro' to TCR, that uses the stats to generate quick-retro.md with an extra question (size of failures vs size of successes) based on stats
• We will ask participants to fill up this generated quick-retro.md as usual

Later, if we think this is useful, we could also

• Generate questions for each failure, asking participants to reflect and find lessons as to why they made this failure
• Use AI to generate a custom retro out of the commit log

Alternatives

We thought of other experiments:

• golf score on size of commits
• leaderboard on size of commits
• specific questions per kata
• let coach add custom questions per kata
• tag commits as "remarkable"

We could also have:

• removed the commit-failures option
• fix the file-update parasites in commit-failures (cf [[Feature]: Running TCR on a slow environment #256])

Additional Context

This is git-only at the moment, as we don't have commit-failures on perforce. Not so much an issue as commit-failures was built for katas more than production work.

Code of Conduct

• I agree to follow this project's Code of Conduct

TODO Map

• Add a stat for the average size of failures and successes
  • Display average size of failures and successes in tcr stats
    • compute the average size of successes in events/tcr_events.go
      • Add a new function to TCREvents to get the stats for pass commits
      • Refactor tests
      • Refactor to TCREvent.totalLineChanges
      • Add doc comments
      • Call this function from stats
      • Make sure it is displayed
    • compute the average size of failures in events/tcr_events.go
      • Add a new function to TCREvents to get the stats for fail commits
      • Call this function from stats
      • Make sure it is displayed
• Add a command 'retro' to TCR, that uses the stats to generate quick-retro.md with an extra question (size of failures vs size of successes) based on stats
  • Add a retro command
  • Add a retro RunMode
  • Call CLI
  • Test CLI
  • Rebase the branch on top of main
  • Implement the tcr.GenerateRetro() function
    • Create a new package Retro
    • implement the template for retro in Retro
      • ❔Time frame for extracting the VCS log. How far in time do we want to go? When does it start?
        • we can stick to the full history in git at the moment. Ok for a 1 session kata. Not suitable otherwise (longer katas or production) Rest can wait
      • ❔What stats do we want to display in the retro? In what format?
        • use the standard Quick Retro.md
      • ❔Where to send the output? stdout, file, file path, web?
        • retro function to output to a writer. TCR can forward this to stdout for now. Later we can do differently
      • Start with an inline mock template with 2 variables
      • move to an embedded text file
      • update the template
      • inject current date
      • inject session title
      • If there is no tcr log, the date should be the current date on the machine
      • Change the title in the md file to only consider the repository name not the full path
      • Pass the file name as a constant instead of passing it as a default name
  • Plug all this together
• We will ask participants to fill up this generated quick-retro.md as usual
• Fill the "Retro" command long description

Parking

• Raise a warning when overwriting the retrospective file
• Allow to specify the path of the retrospective file

Maybe Later if useful

• Pass in a timeframe to restrict to recent commit log history
• Write to something else than stdout
• Embed the full stats.printer() in the generated retro template
• or check for semantic commits meta info "tests passed" + git simple number of lines changed (remove the dependency on tcr events)
• Split the code out of the main TCR tool (in standalone apps, or in a web front-end)

[philou]

We decided to ditch the current implementation of "Commit Failures" and use the "Real TCR" (that also reverts tests) to commit the failures and reverts (see #674). We'll wait for this one to be done first