git-gamble-1.3.0 is not a library.

Visit the last successful build: git-gamble-2.7.0

Git-Gamble

Blend TCR (test && commit || revert) + TDD (Test Driven Development) to make sure to develop the right thing, babystep by babystep

Original idea by Xavier Detant

[[TOC]]

Theory

TCR

TCR (test && commit || revert) is cool! It encourages doing baby steps, reducing the waste when we are wrong

But it doesn't allow us to see the tests failing

So:

Maybe we test nothing (assert forgotten)

def test_should_be_Buzz_given_5():
    input = 5
    actual = fizz_buzz(input)
    # Oops! Assert has been forgotten

Maybe we are testing something that is not the thing we should be testing

it("should be Fizz given 3", () => {
  const input = 3;
  const actual = fizzBuzz(input);
  expect(input).toBe("Fizz");
  // Oops! Asserts on the input value instead of the actual value
});

TDD

TDD (Test Driven Development) is cool! It makes sure we develop the right thing, step by step

TCRDD

TCRDD = TCR + TDD

TCRDD blends the constraints of the two methods to benefit from their advantages

Therefore, TCRDD makes sure we develop the right thing, step by step, and we are encouraged to do so by baby steps, reducing the waste when we are wrong

@startuml
skinparam ArrowColor black

start
repeat
	partition "red" #Coral {
		repeat
			:Write a test]
			:Gamble that the tests fail/
			if (Actually run tests) then (Fail)
				-[#Red]->
				:Commit;
				break
			else (Pass)
				-[#Green]->
				:Revert;
			endif
		repeat while (Write another test)
	}
	partition "green" #Lime {
		repeat
			:Write the minimum code]
			:Gamble that the tests pass/
			if (Actually run tests) then (Pass)
				-[#Green]->
				:Commit;
				break
			else (Fail)
				-[#Red]->
				:Revert;
			endif
		repeat while (Try something else)
	}
	partition "refactor" #668cff {
		repeat
			repeat
				:Write code
				without changing the behavior]
				:Gamble that the tests pass/
				if (Actually run tests) then (Pass)
					-[#Green]->
					:Commit;
					break
				else (Fail)
					-[#Tomato]->
					:Revert;
				endif
			repeat while (Change something else)
		repeat while (Another things to refactor ?)
	}
repeat while (Another feature to add ?)
stop
@enduml

git-gamble is a tool that helps to use the TCRDD method

How to install

Requirements

git-gamble doesn't repackage git, it use the one installed on your system

Install git

Be sure to make it available in your $PATH, you can check with this command

git --help

AppImage

Go to the package registry page
Go to the latest version of git-gamble-AppImage
Download the latest version git-gamble-v1.3.0-x86_64.AppImage

Make it executable

chmod +x git-gamble-v1.3.0-x86_64.AppImage

Put it your $PATH

# for example
mkdir -p ~/.local/bin
mv git-gamble-v1.3.0-x86_64.AppImage ~/.local/bin/git-gamble
export PATH+=":~/.local/bin"

This is not really convenient but the others ways need to be logged in to the GitLab API, contributions are welcome

This will (hopefully) be better when GitLab will allow to download public package without authentification

Debian

Go to the package registry page
Go to the latest version of git-gamble-debian
Download the latest version git-gamble_1.3.0_amd64.deb
Install package

As root
```
dpkg --install git-gamble*.deb
```

This is not really convenient but a better way will come when GitLab Debian Package Manager MVC will be available

Mac OS X / Homebrew

Install Homebrew

brew tap pinage404/git-gamble https://gitlab.com/pinage404/git-gamble.git
brew install --HEAD git-gamble

Windows / Chocolatey

Install Chocolatey

Go to the package registry page
Go to the latest version of git-gamble.portable
Download the latest version git-gamble.portable.1.3.0.nupkg
Install package

Follow GitLab's documentation and Chocolatey's documentation
```
choco install ./git-gamble.portable.1.3.0.nupkg
```

This is not really convenient, contributions are welcome

Nix / NixOS

Copy the Nix file

This is really basic but, like everything else, contributions are welcome

Cargo

Install Cargo

cargo install git-gamble

Add ~/.cargo/bin to your $PATH

Fish:

set --export --append PATH ~/.cargo/bin

Bash / ZSH:

export PATH=$PATH:~/.cargo/bin

Check the installation

Check if all have been well settled

git gamble

If it has been well settled, it should output this :

error: The following required arguments were not provided:
    <test-command>...
    <--pass|--fail>

USAGE:
    git-gamble --repository-path <repository-path> <--pass|--fail>

For more information try --help

If it has been badly settled, it should output this :

git : 'gamble' is not a git command. See 'git --help'.

How to use

To see all available flags and options

git-gamble --help # dash is only needed for --help

Write a failing test in your codebase, then :
```
git gamble --fail -- $YOUR_TEST_COMMAND
```
Write the minimum code to make tests pass, then :
```
git gamble --pass -- $YOUR_TEST_COMMAND
```

Refactor your code, then :

git gamble --pass -- $YOUR_TEST_COMMAND

It's a bit tedious to always repeat the test command

So you can set an environment variable with the test command to avoid repeating it all the time

export GAMBLE_TEST_COMMAND="sh -c 'cargo fix --allow-dirty ; cargo clippy --all-targets ; cargo check --all-targets ; cargo fmt ; cargo test'"
git gamble --pass

Test command must exit with a 0 status when there are 0 failing tests, anything else is considered as a failure

Backlog

@startmindmap "backlog"
* Backlog
left side
	* Done
		* MVP
			* base
				* run tests
				* `git commit`
				* `git revert`
				* test it
			* TCR
				* option --pass
			* TRC
				* option --fail
		* give path in option
		* improve test command
			* test command with arguments
			* script
		* dry run flag
		* help option
			* -h
			* --help
		* exclusive flag
		* required flag
		* option colors
			* -g
			* --green
			* -r
			* --red
		* merge commits
			* `git update-ref`
			* `git commit --amend`
		* should fail without test command
		* test command from environement variable
		* display when committed or reverted
		* how to use
		* test in isolated and reproductible environement
			* container
			* CI
			* [[https://doc.rust-lang.org/cargo/guide/continuous-integration.html Cargo's Documentation about CI]]
		* complete metadata
		* rename project?
			* simpler to say and understand and remember when not familiar with `TCR` or `TDD`
			* from `git-tcrdd` to `git-...`?
				* [[https://www.wordreference.com/fren/jouer jouer?]]
				* [[https://www.wordreference.com/fren/parier parier?]]
				* [[https://www.wordreference.com/enfr/bet bet?]]
				* [[https://www.wordreference.com/enfr/expect expect?]]
				* [[https://www.wordreference.com/enfr/gamble gamble?]]
				* [[https://www.wordreference.com/enfr/should should?]]
				* Quick save development (qsd)
		* TDD's option `--refactor` == `--pass`
		* message option
			* -m
			* --message
			* amend should keep message
				* `"--reuse-message=@",`
		* shell completion
			* shells
				* [x] Fish
				* [x] Bash
				* [x] Zsh
			* package
				* [x] Debian
				* [x] Homebrew
	* WIP
right side
	* TODO
		* `--edit` OR `--edit-message` option to open `$EDITOR` on commit like `git commit --edit`
			* how to test it ?
		* when revert `git clean`
		* `git workspace` support
			* `git update-ref` should contain an unique identifier to the workspace
				* branche name ?
				* folder path ?
		* gamble hooks
			* branch based developement
				* `git commit --fixup`
				* `git rebase --autosquash`
			* trunk based developement
				* `git pull`
				* `git push`
		* like git, flags & options & arguments should be retrieved from CLI or environment variable or config's file
			* re-use `git config` to store in file ?
			* repository level config using direnv and environment variable ?
		* [[https://rachelcarmena.github.io/2018/11/13/test-driven-programming-workflows.html#my-proposal-of-tcr-variant stash instead of revert ?]]
		* `--help` should link to the repository
		* shell completion
			* in the package ?
				* [ ] Cargo
				* [ ] AppImage
				* [ ] Chocolatey
			* in sub command ?
			* for `git gamble` not only `git-gamble`
@endmindmap

Distribution / publishing backlog

OS distribution
- Linux
  - Move packages distribution from BinTray to elsewhere (GitLab ?)
    1. AppImage
      - upload package elsewhere
      - update installation instructions
      - remove BinTray links
    2. Chocolatey
      - upload package elsewhere
      - update installation instructions
    3. Debian
      - upload package elsewhere
      - update installation instructions
      - remove BinTray links
    4. changelog BinTray breaking change
    5. 2.0.0
      - remove BinTray badges
      - remove BinTray job
      - remove BinTray CI variables
  - Nix
  - RPM
    - cargo-rpm
  - make AppImage updatable
    - bintray-zsync|pinage404|git-gamble-AppImages|git-gamble|git-gamble-_latestVersion-x86_64.AppImage.zsync
  - SnapCraft ?
    - snapcraft's docs about rust
  - FlatPak ?
  - fpm : tool that help to generate to several packages
  - document AppImage with firejail ?
  - document AppImage with bubblewrap ?
  - Open Build Service seems to be a service that build for every Linux targets
    - it can be use
      - thougth REST
        
        badly documented
      - with ocs a CLI who seems to be a VCS like SVN (commit = commit + push)
        
        who use the REST API under the hood
- Container Image (Docker) ?
- Awesome Rust Deployment
- Awesome Rust Platform Specific
URL to download latest version
- symlinks to URL containing the version name ?
- using GitLab Pages ?
versioned Homebrew Formula
- Use Cargo-Release to bump version
- how to update sha256 in the versioned file ?

Adding package to the X packages repository

Where the X packages repository is e.g. Nixpgks, Debian, Homebrew, Chocolatey ...

Feel free to do it, we don't plan to do it at the moment, it's too long to learn and understand how each of them works

If you do it, please file an issue or open an MR to update the documentation

CheckList

package in local
package in CI
upload
make public available
complete how to install
manual test
update backlog

Technical improvement opportunities

licence check
- cargo license
- cargo deny
code coverage
- tarpaulin
- kcov
smaller binary
- cargo bloat
- cargo deps

Reinvent the wheel

Why reinvent the wheel?

This script already works well

Because i would like to learn Rust ¯\_(ツ)_/¯

Contributing

Any contributions (feedback, bug report, merge request ...) are welcome

Respect the code of conduct

Follow Keep a Changelog

Development

To contribute with merge request

Simple

Install Direnv

Install Nix

Let direnv automagically set up the environment by executing the following command in the project directory

direnv allow

Manual

Rustup
clippy
rustfmt
rustfix
PlantUML if you want to see diagrams

Deployment

cargo release

git-gamble 1.3.0