Skip to content

Commit

Permalink
Set a stance regarding lifetimes usage.
Browse files Browse the repository at this point in the history
Related to #675
and Canop/bacon#98.
  • Loading branch information
Byron committed Dec 30, 2022
1 parent 5a97bb5 commit efe0c13
Showing 1 changed file with 13 additions and 3 deletions.
16 changes: 13 additions & 3 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,9 +184,19 @@ A bunch of notes collected to keep track of what's needed to eventually support

## `Options` vs `Context`

- Use `Options` whenever there is something to configure in terms of branching behaviour. It can be defaulted, and if it can't these fields should be parameters.
- Use `Context` when potential optional data is required to perform an operation at all. See `git_config::path::Context` as reference. It can't be defaulted and the
fields could also be parameters.
- Use `Options` whenever there is something to configure in terms of branching behaviour. It can be defaulted, and if it can't these fields should be parameters of the method
that takes these `Options`.
- Use `Context` when data is required to perform an operation at all. See `git_config::path::Context` as reference. It can't be defaulted and the fields could also be parameters.

## Lifetimes

In _plumbing_ crates, prefer to default to keeping references if this is feasible to avoid typically expensive clones.

In _porcelain_ crates, like `git-repository`, we have `Platforms` which are typically cheap enough to create on demand as they configure one or more method calls. These
should keep a reference to the `Repository` instance that created them as the user is expected to clone the `Repository` if there is the need.
However, if these structures are more expensive, call them `Cache` or `<NotPlatform>` and prefer to clone the `Repository` into them or otherwise keep them free of lifetimes
to allow the user to keep this structure around for repeated calls. References for this paragraph are [this PR](https://github.com/Canop/bacon/pull/98) and
[this discussion](https://github.com/Byron/gitoxide/discussions/675).

## Examples, Porcelain CLI and Plumbing CLI - which does what?

Expand Down

0 comments on commit efe0c13

Please sign in to comment.