You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: DEVELOPMENT.md
+28-29
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Development Guide
2
2
3
-
## Practices
3
+
## Practices
4
4
5
5
***test-first development**
6
6
* protect against regression and make implementing features easy.
@@ -9,12 +9,12 @@
9
9
for the mundane things, like unhappy code paths.
10
10
**use git itself* as reference implementation, and use their test-cases and fixtures where
11
11
appropriate. At the very least, try to learn from them.
12
-
* Run the same test against git whenever feasible to assure git agrees with our implementation.
12
+
* Run the same test against git whenever feasible to assure git agrees with our implementation.
13
13
See `gix-glob` for examples.
14
14
**use libgit2* test fixtures and cases where appropriate, or learn from them.
15
15
***safety first**
16
16
* handle all errors, never `unwrap()`. If needed, `expect("why")`.
17
-
* provide an error chain and make it easy to understand what went wrong.
17
+
* provide an error chain and make it easy to understand what went wrong.
18
18
* We `thiserror` generally.
19
19
* Adhere to the [stability guide](https://github.com/Byron/gitoxide/blob/main/STABILITY.md)
20
20
@@ -28,10 +28,10 @@ The _subject_ usually informs about the *what* and the body provides details and
28
28
Commit messages _must_ show up in the changelog in case of breaking changes. Examples for that are:
29
29
30
30
- change!: rename `Foo` to `Bar`. (#123)
31
-
31
+
32
32
And this is why we do it in the body.
33
33
- remove!: `Repository::obsolete()`.
34
-
34
+
35
35
Nobody used this method.
36
36
37
37
Features or other changes that are visible and people should know about look like this:
@@ -48,7 +48,7 @@ Examples could be:
48
48
-`make fmt`
49
49
- thanks clippy
50
50
51
-
Please refrain from using `chore:` or `refactor:` prefixes as for the most part, users of the API don't care about those. When a `refactor`
51
+
Please refrain from using `chore:` or `refactor:` prefixes as for the most part, users of the API don't care about those. When a `refactor`
52
52
changes the API in some way, prefer to use `feat`, `change`, `rename` or `remove` instead, and most of the time the ones that are not `feat`
53
53
are breaking so would be seen with their _exclamation mark_ suffix, like `change!`.
54
54
@@ -63,20 +63,20 @@ Knowing that `cargo smart-release` is driven by commit messages and affects thei
63
63
to split edits into multiple commits to clearly indicate which crate is actually broken.
64
64
65
65
Typical patterns include making a breaking change in one crate and then fix all others to work with it. For changelogs to look proper
66
-
and version bumps to be correct, the first commit would contain only the breaking changes themselves,
66
+
and version bumps to be correct, the first commit would contain only the breaking changes themselves,
67
67
like "rename: `foo()` to `bar()`", and the second commit would contain all changes to adapt to that and look like "adapt to changes in `<crate name>`".
68
68
69
69
## Commit History
70
70
71
-
We generally follow a 'track everything' approach and there is a lot of freedom leading to more commits rather than less. There
71
+
We generally follow a 'track everything' approach and there is a lot of freedom leading to more commits rather than less. There
72
72
is no obligation to squash commits or to otherwise tune the history.
73
73
74
74
We use feature branches and PRs most of the time to be able to take advantage of CI and GitHub review tools, and merge with merge commits
75
-
to make individual efforts stand out. There is no need for linearizing history or tuning it in any other way. However, each commit
75
+
to make individual efforts stand out. There is no need for linearizing history or tuning it in any other way. However, each commit
76
76
_must_ follow the guidelines laid out in the `Commit Messages` paragraph.
77
77
78
78
There is value in organizing commits by topic and [_Stacked Git_](https://stacked-git.github.io) is hereby endorsed to do that.
79
-
79
+
80
80
## Configuration and overrides
81
81
82
82
As a general rule, respect and implement all applicable [git-config](https://git-scm.com/docs/git-config) by default, but allow the
@@ -102,11 +102,11 @@ Parameters which are not available in git or specific to `gitoxide` or the needs
102
102
***User Interfaces**
103
103
* User interfaces can greatly benefit from using async as it's much easier to maintain a responsive UI thread that way thanks
104
104
to the wonderful future combinators.
105
-
*`blocking` can be used to make `Read` and `Iterator` async, or move any operation onto a thread which blends it into the
106
-
async world.
105
+
*`blocking` can be used to make `Read` and `Iterator` async, or move any operation onto a thread which blends it into the
106
+
async world.
107
107
* Most operations are fast and 'interrupting' them is as easy as ignoring their result by cancelling their task.
108
108
* Long-running operations can be roughly interacted with using `gix_features::interrupt::trigger()` function, and after a moment
109
-
of waiting the flag can be unset with the `…::uninterrupt()` function to allow new long-running operations to work.
109
+
of waiting the flag can be unset with the `…::uninterrupt()` function to allow new long-running operations to work.
110
110
Every long running operation supports this.
111
111
***server-side**
112
112
*~~Building a pack is CPU and at some point, IO bound, and it makes no sense to use async to handle more connections - git
@@ -119,15 +119,15 @@ Parameters which are not available in git or specific to `gitoxide` or the needs
119
119
***Why not use it to generate blocking versions of traits automatically?**
120
120
* This would require `maybe_async` and its dependencies to always be present, increasing compile times. For now we chose a little more code to handle
121
121
over increasing compile times for everyone. This stance may change later once compile times don't matter that much anymore to allow the removal of code.
122
-
122
+
123
123
***`Default` trait implementations**
124
124
* These can change only if the effect is contained within the callers process.
125
125
This means **changing the default of a file version** is a **breaking change**.
126
126
***Using the `Progress` trait**
127
127
* When receiving a `Progress` implementation
128
128
* without calling `add_child(…)` then use it directly to communicate progress, leaving
129
129
control of the name to the caller. However, call `.init(…)` to configure the iteration.
130
-
* and when calling `add_child(…)` don't use the parent progress instance for anything else.
130
+
* and when calling `add_child(…)` don't use the parent progress instance for anything else.
131
131
***interruption of long-running operations**
132
132
* Use `gix-features::interrupt::*` for building support for interruptions of long-running operations only.
133
133
* It's up to the author to decide how to best integrate it, generally we use a poll-based mechanism to check whether
@@ -136,9 +136,9 @@ Parameters which are not available in git or specific to `gitoxide` or the needs
136
136
* …temporary resources like files might otherwise be leaked.
137
137
***this is optional but desirable if…**
138
138
* …there is no leakage otherwise to support user interfaces. They background long-running operations and need them to be cancellable.
139
-
139
+
140
140
***prepare for SHA256 support by using `gix_hash::ObjectId` and `gix_hash::oid`**
141
-
* eventually there will be the need to support both Sha1 and Sha256. We anticipate it by using the `Id` type instead
141
+
* eventually there will be the need to support both Sha1 and Sha256. We anticipate it by using the `Id` type instead
142
142
of slices or arrays of 20 bytes. This way, eventually we can support multiple hash digest sizes.
143
143
* Right now it's unclear how Sha256 is going to work in git, so we only support Sha1 for now. It might be an avenue to proactively
144
144
implement it ahead of time once there is a specification to follow.
@@ -166,7 +166,7 @@ Parameters which are not available in git or specific to `gitoxide` or the needs
166
166
- Assuming UTF8-ish bytes in paths produced by `git` even on windows due to `MSYS2`, we use `os_str_bytes` to convert these back into `OsStr` and derivatives like `Path`
167
167
as needed even though it might not always be the case depending on the actual encoding used by `MSYS2` or other abstraction layers, or avoiding to use std types altogether
168
168
using our own instead.
169
-
169
+
170
170
## Sha256
171
171
172
172
A bunch of notes collected to keep track of what's needed to eventually support it
@@ -181,7 +181,7 @@ A bunch of notes collected to keep track of what's needed to eventually support
181
181
* don't use unwrap, not even in tests. Instead use `quick_error!()` or `Box<dyn std::error::Error>`.
182
182
* Use `expect(…)` as assertion on Options, providing context on *why* the expectations should hold. Or in other words,
183
183
answer "This should work _because_…<expect(…)>"
184
-
184
+
185
185
## `Options` vs `Context`
186
186
187
187
- 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
@@ -195,7 +195,7 @@ In _plumbing_ crates, prefer to default to keeping references if this is feasibl
195
195
In _porcelain_ crates, like `gix`, we have `Platforms` which are typically cheap enough to create on demand as they configure one or more method calls. These
196
196
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.
197
197
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
198
-
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
198
+
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
0 commit comments