Unified · Split
| @@ -28,10 +28,10 @@ default = ["max"] · 27 unmodified lines | ||
| 28 | 28 | max = ["fast", "pretty-cli", "prodash/tui-renderer-crossterm", "prodash-line-renderer-crossterm"] |
| 29 | 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"] | |
| 32 | −lean-termion = ["fast", "lean-cli", "prodash-line-renderer-termion"] | |
| 31 | +lean = ["fast", "lean-cli", "prodash-line-renderer-crossterm", "git-features/interruptible"] | |
| 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 | 35 | small = ["lean-cli"] |
| 36 | 36 | |
| 37 | 37 | fast = ["git-features/parallel", "git-features/fast-sha1"] |
| @@ -45,7 +45,7 @@ pretty-cli = ["structopt", · 7 unmodified lines | ||
| 45 | 45 | "prodash/localtime", |
| 46 | 46 | "env_logger", |
| 47 | 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 | 50 | prodash-line-renderer-crossterm = ["prodash-line-renderer", "prodash/line-renderer-crossterm", "git-features/progress-prodash", "atty", "crosstermion"] |
| 51 | 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 | 3 | ### Practices |
| 2 | 4 | |
| 3 | 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 | 69 | * Use `expect(…)` as assertion on Options, providing context on *why* the expectations should hold. Or in other words, |
| 68 | 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 | 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 | 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 | 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 | 28 | cargo build --release --no-default-features --features light |
| 26 | 29 | |
| 27 | 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 | 35 | debug-default: always ## the default build, big but pretty |
| 33 | 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 | 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 | 45 | cargo build --no-default-features --features light |
| 40 | 46 | |
| 41 | 47 | debug-small: always ## minimal dependencies, at cost of performance |
| @@ -199,13 +199,6 @@ Once installed, there are two binaries: · 198 unmodified lines | ||
| 199 | 199 | * libraries use light-weight custom errors implemented using `quick-error`. |
| 200 | 200 | * internationalization is nothing we are concerned with right now. |
| 201 | 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 | 203 | ## Non-Goals |
| 211 | 204 | |
| @@ -217,6 +210,8 @@ Once installed, there are two binaries: · 5 unmodified lines | ||
| 217 | 210 | * **use async IO everywhere** |
| 218 | 211 | * for the most part, git operations are heavily relying on memory mapped IO as well as CPU to decompress data, |
| 219 | 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 | 215 | * When connecting or streaming over TCP connections, especially when receiving on the server, async seems like a must |
| 221 | 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 | 334 | * If timestamps are shown, they are in localtime. |
| 340 | 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 | 337 | ## Shortcomings |
| 371 | 338 | |
| 372 | 339 | * **lean** and **light** and **small** builds don't support non-UTF-8 paths |