Unified · Split
| @@ -28,10 +28,10 @@ default = ["max"] · 27 unmodified lines | |||
| 28 | max = ["fast", "pretty-cli", "prodash/tui-renderer-crossterm", "prodash-line-renderer-crossterm"] | 28 | max = ["fast", "pretty-cli", "prodash/tui-renderer-crossterm", "prodash-line-renderer-crossterm"] |
| 29 | max-termion = ["fast", "pretty-cli", "prodash/tui-renderer-termion", "prodash-line-renderer-termion"] | 29 | max-termion = ["fast", "pretty-cli", "prodash/tui-renderer-termion", "prodash-line-renderer-termion"] |
| 30 | 30 | ||
| 31 | lean = ["fast", "lean-cli", "prodash-line-renderer-crossterm"] | 31 | lean = ["fast", "lean-cli", "prodash-line-renderer-crossterm", "git-features/interruptible"] |
| 32 | lean-termion = ["fast", "lean-cli", "prodash-line-renderer-termion"] | 32 | lean-termion = ["fast", "lean-cli", "prodash-line-renderer-termion", "git-features/interruptible"] |
| 33 | 33 | ||
| 34 | light = ["fast", "lean-cli"] | 34 | light = ["fast", "lean-cli", "git-features/interruptible"] |
| 35 | small = ["lean-cli"] | 35 | small = ["lean-cli"] |
| 36 | 36 | ||
| 37 | fast = ["git-features/parallel", "git-features/fast-sha1"] | 37 | fast = ["git-features/parallel", "git-features/fast-sha1"] |
| @@ -45,7 +45,7 @@ pretty-cli = ["structopt", · 7 unmodified lines | |||
| 45 | "prodash/localtime", | 45 | "prodash/localtime", |
| 46 | "env_logger", | 46 | "env_logger", |
| 47 | "futures-lite"] | 47 | "futures-lite"] |
| 48 | lean-cli = ["argh", "git-features/progress-log", "env_logger", "git-features/interruptible"] | 48 | lean-cli = ["argh", "git-features/progress-log", "env_logger"] |
| 49 | 49 | ||
| 50 | prodash-line-renderer-crossterm = ["prodash-line-renderer", "prodash/line-renderer-crossterm", "git-features/progress-prodash", "atty", "crosstermion"] | 50 | prodash-line-renderer-crossterm = ["prodash-line-renderer", "prodash/line-renderer-crossterm", "git-features/progress-prodash", "atty", "crosstermion"] |
| 51 | prodash-line-renderer-termion = ["prodash-line-renderer", "prodash/line-renderer-termion", "git-features/progress-prodash", "atty", "crosstermion"] | 51 | prodash-line-renderer-termion = ["prodash-line-renderer", "prodash/line-renderer-termion", "git-features/progress-prodash", "atty", "crosstermion"] |
| @@ -1,3 +1,5 @@ | |||
| 1 | ## Development Guide | ||
| 2 | |||
| 1 | ### Practices | 3 | ### Practices |
| 2 | 4 | ||
| 3 | * **test-first development** | 5 | * **test-first development** |
| @@ -67,3 +69,32 @@ A bunch of notes collected to keep track of what's needed to eventually support · 63 unmodified lines | |||
| 67 | * Use `expect(…)` as assertion on Options, providing context on *why* the expectations should hold. Or in other words, | 69 | * Use `expect(…)` as assertion on Options, providing context on *why* the expectations should hold. Or in other words, |
| 68 | answer "This should work _because_…<expect(…)>" | 70 | answer "This should work _because_…<expect(…)>" |
| 69 | 71 | ||
| 72 | |||
| 73 | ## Maintenance Guide | ||
| 74 | |||
| 75 | Utilities to aid in keeping the project fresh and in sync can be found in the `Maintenance` section of the `makefile`. Run `make` to | ||
| 76 | get an overview. | ||
| 77 | |||
| 78 | ### Creating a release | ||
| 79 | |||
| 80 | Run `etc/release.sh` to release all crates in leaf-first order using `cargo release`. | ||
| 81 | |||
| 82 | ### Which git-version to chase? | ||
| 83 | |||
| 84 | Generally, we take the git version installed on ubuntu-latest as the one we stay compatible with (_while maintaining backwards | ||
| 85 | compatibility_). Certain tests only run on CI, designed to validate certain assumptions still hold against possibly changed | ||
| 86 | git program versions. | ||
| 87 | |||
| 88 | This also means that CI may fail despite everything being alright locally, and the fix depends on the problem at hand. | ||
| 89 | |||
| 90 | ### How to update fixtures | ||
| 91 | |||
| 92 | Fixtures are created by using a line like this which produces a line we ignore via `tail +1` followed by the un-prettified object payload | ||
| 93 | trailed by a newline. | ||
| 94 | ```sh | ||
| 95 | echo c56a8e7aa92c86c41a923bc760d2dc39e8a31cf7 | git cat-file --batch | tail +2 > fixture | ||
| 96 | ``` | ||
| 97 | |||
| 98 | Thus one has to post-process the file by reducing its size by one using `truncate -s -1 fixture`, **removing the newline byte**. | ||
| 99 | |||
| 100 | |||
| @@ -15,13 +15,16 @@ interactive-developer-environment-in-docker: ## Use docker for all dependencies · 14 unmodified lines | |||
| 15 | 15 | ||
| 16 | release: release-default release-lean release-small ## all release builds | 16 | release: release-default release-lean release-small ## all release builds |
| 17 | 17 | ||
| 18 | release-default: always ## the default build, big but pretty and cross-platform (builds in ~2min 35s) | 18 | release-default: always ## the default build, big but pretty (builds in ~2min 35s) |
| 19 | cargo build --release | 19 | cargo build --release |
| 20 | 20 | ||
| 21 | release-lean: always ## lean and fast and cross-platform (builds in ~1min 30s) | 21 | release-default-unix: always ## the default build, big but pretty, unix only (builds in ~2min 35s) |
| 22 | cargo build --release --no-default-features --features max-termion | ||
| 23 | |||
| 24 | release-lean: always ## lean and fast, with line renderer (builds in ~1min 30s) | ||
| 22 | cargo build --release --no-default-features --features lean | 25 | cargo build --release --no-default-features --features lean |
| 23 | 26 | ||
| 24 | release-light: always ## lean and fast and unix-only (builds in ~1min 14s) | 27 | release-light: always ## lean and fast, log only (builds in ~1min 14s) |
| 25 | cargo build --release --no-default-features --features light | 28 | cargo build --release --no-default-features --features light |
| 26 | 29 | ||
| 27 | release-small: always ## minimal dependencies, at cost of performance (builds in ~46s) | 30 | release-small: always ## minimal dependencies, at cost of performance (builds in ~46s) |
| @@ -32,10 +35,13 @@ release-small: always ## minimal dependencies, at cost of performance (builds in · 4 unmodified lines | |||
| 32 | debug-default: always ## the default build, big but pretty | 35 | debug-default: always ## the default build, big but pretty |
| 33 | cargo build | 36 | cargo build |
| 34 | 37 | ||
| 35 | debug-lean: always ## lean and fast | 38 | debug-default-unix: always ## the default build, big but pretty, unix only |
| 39 | cargo build --no-default-features --features max-termion | ||
| 40 | |||
| 41 | debug-lean: always ## lean and fast, with line renderer | ||
| 36 | cargo build --no-default-features --features lean | 42 | cargo build --no-default-features --features lean |
| 37 | 43 | ||
| 38 | debug-light: always ## lean and fast, unix only | 44 | debug-light: always ## lean and fast |
| 39 | cargo build --no-default-features --features light | 45 | cargo build --no-default-features --features light |
| 40 | 46 | ||
| 41 | debug-small: always ## minimal dependencies, at cost of performance | 47 | debug-small: always ## minimal dependencies, at cost of performance |
| @@ -199,13 +199,6 @@ Once installed, there are two binaries: · 198 unmodified lines | |||
| 199 | * libraries use light-weight custom errors implemented using `quick-error`. | 199 | * libraries use light-weight custom errors implemented using `quick-error`. |
| 200 | * internationalization is nothing we are concerned with right now. | 200 | * internationalization is nothing we are concerned with right now. |
| 201 | * IO errors due to insufficient amount of open file handles don't always lead to operation failure | 201 | * IO errors due to insufficient amount of open file handles don't always lead to operation failure |
| 202 | * **async as opt-in** | ||
| 203 | * Making certain capabilities available through `async` APIs allows for abortable operations, which | ||
| 204 | may be interesting for interactive user interfaces. Thus it is something worth considering, but only | ||
| 205 | behind a feature flag and once the need transpires. | ||
| 206 | * Ideally many operations powered by implementors of `std::io::{Read, Write}` and `std::iter::Iterator`, | ||
| 207 | which makes unblocking them trivial using the fantastic `blocking` crate. Only when these are used internally, | ||
| 208 | providing a separate async version of these operations can be beneficial to make them abortable. | ||
| 209 | 202 | ||
| 210 | ## Non-Goals | 203 | ## Non-Goals |
| 211 | 204 | ||
| @@ -217,6 +210,8 @@ Once installed, there are two binaries: · 5 unmodified lines | |||
| 217 | * **use async IO everywhere** | 210 | * **use async IO everywhere** |
| 218 | * for the most part, git operations are heavily relying on memory mapped IO as well as CPU to decompress data, | 211 | * for the most part, git operations are heavily relying on memory mapped IO as well as CPU to decompress data, |
| 219 | which doesn't lend itself well to async IO out of the box. | 212 | which doesn't lend itself well to async IO out of the box. |
| 213 | * Use `blocking` as well as `git-features::interruptible` to bring operations into the async world and to control | ||
| 214 | long running operations. | ||
| 220 | * When connecting or streaming over TCP connections, especially when receiving on the server, async seems like a must | 215 | * When connecting or streaming over TCP connections, especially when receiving on the server, async seems like a must |
| 221 | though. It should be possible to put it behind a feature flag though. | 216 | though. It should be possible to put it behind a feature flag though. |
| 222 | 217 | ||
| @@ -339,34 +334,6 @@ From there, we can derive a few rules to try adhere to: · 116 unmodified lines | |||
| 339 | * If timestamps are shown, they are in localtime. | 334 | * If timestamps are shown, they are in localtime. |
| 340 | * Non-progress information goes to stdout. | 335 | * Non-progress information goes to stdout. |
| 341 | 336 | ||
| 342 | ## Maintenance Guide | ||
| 343 | |||
| 344 | Utilities to aid in keeping the project fresh and in sync can be found in the `Maintenance` section of the `makefile`. Run `make` to | ||
| 345 | get an overview. | ||
| 346 | |||
| 347 | ### Creating a release | ||
| 348 | |||
| 349 | Run `etc/release.sh` to release all crates in leaf-first order using `cargo release`. | ||
| 350 | |||
| 351 | ### Which git-version to chase? | ||
| 352 | |||
| 353 | Generally, we take the git version installed on ubuntu-latest as the one we stay compatible with (_while maintaining backwards | ||
| 354 | compatibility_). Certain tests only run on CI, designed to validate certain assumptions still hold against possibly changed | ||
| 355 | git program versions. | ||
| 356 | |||
| 357 | This also means that CI may fail despite everything being alright locally, and the fix depends on the problem at hand. | ||
| 358 | |||
| 359 | ### How to update fixtures | ||
| 360 | |||
| 361 | Fixtures are created by using a line like this which produces a line we ignore via `tail +1` followed by the un-prettified object payload | ||
| 362 | trailed by a newline. | ||
| 363 | ```sh | ||
| 364 | echo c56a8e7aa92c86c41a923bc760d2dc39e8a31cf7 | git cat-file --batch | tail +2 > fixture | ||
| 365 | ``` | ||
| 366 | |||
| 367 | Thus one has to post-process the file by reducing its size by one using `truncate -s -1 fixture`, **removing the newline byte**. | ||
| 368 | |||
| 369 | |||
| 370 | ## Shortcomings | 337 | ## Shortcomings |
| 371 | 338 | ||
| 372 | * **lean** and **light** and **small** builds don't support non-UTF-8 paths | 339 | * **lean** and **light** and **small** builds don't support non-UTF-8 paths |