1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
bcachefs contributor's guide:
=============================
The first thing to get out of the way: I aim to hold bcachefs code to a very
high standard of quality, which is going to be considerably higher than most
people are used to, even those with previous filesystems experience.
I want to be very up front about this because I know from prior experience that
this can be hard on people and a source of considerable friction, but my goal
isn't to make people's lives more difficult - quite the opposite. My purpose
is that I hate debugging, and I don't know anyone else who enjoys debugging -
particularly when you're responsible for chasing down bugs that are responsible
for corrupting customer data and you can't reproduce yourself. That's no fun and
it can be incredibly stressful.
If, instead, we are successful in keeping the bcachefs codebase as stable and
reliable as possible - that means getting to do development at a much more
leisurely pace, uninterrupted by fires that need putting out and with much more
time for lazy afternoons going hiking or drinking mojitos.
How do we actually get to this promised land of filesystem development?
* Be selective about new features and new code. If you've got a feature
request, and you can't figure out a way of doing it that doesn't make the
codebase worse - don't do it. I don't care what the business case is, it's
not worth it and I won't merge it.
This usually won't mean saying no to people, but it often will mean having to
think hard before coming up with a way of doing something that lets you say
yes.
* Take as much time as you need. Don't rush.
We developers should always remember that bcachefs - indeed most of our
filesystems - already works for the vast majority of users, and already does
everything we really need it to do. Any more improvements are just gravy.
So there's really no rush to do even more stuff, and it makes no sense to
rush if it comes at the cost of bugs that affect the people for whom bcachefs
does already work for.
Also, with any new feature the cost in developer time after it gets merged -
debugging, ongoing maintenance - is usually far higher than the cost of
initial development up until when it's first merged.
To a large degree this is always going to be unavoidable, but keeping this in
mind when writing code should help you go the extra mile and make it as bug
free as you possibly can. Remember that it's far easier to debug something
when you find it yourself and you've got the test case right in front of
you.
* Don't overengineer. Leave anything out if you aren't convinced there's value
in it. KISS, and be utterly ruthless in this.
Customers will ask for all kinds of features they want, but don't actually
need. But even worse are developers - developers will come up with all kinds
of ideas that sound wonderful and cool, and get attached to them, often
regardless of if they're actually necessary - and the trouble with developers
is that they have the skills to turn their bad ideas into code.
Even after you've written something, you have to be able to honestly ask
yourself if it still seems like a good idea and if it turned out well enough.
I've written and not merged almost as much of my own code as I've written and
merged.
* Prioritize refactoring and improving existing code over adding new code.
Most of the code in bcachefs is now in a state when I'm reasonably happy with
it, and I can modify it without being scared of breaking things - but most of
the code didn't get to that point without rewriting or heavily refactoring it
four or five or six times. Not all the code is at that point - in particular,
some of the btree iterator code is still too tricky and subtle. And the code
relating to asynchronous interior btree updates is - I believe - sound, but
definitely needs to be clearer.
This is the normal order of things; it almost always takes quite a few
attempts before we find clear, understandable, maintainable ways of
expressing things, but we need to in order to keep the codebase in a state
where it's sound enough to build new things on top of.
* Incremental development is only way anything comes out halfway decent.
There are some fiendishly complicated and sophisticated things going on in
bcachefs, most of them within the btree code. The locking, the iterators, the
asynchronous interior btree node updates, the auxiliary lookup tables in
bset.c...
Without exception, those features all started out from very humble beginnings
and were added to bit by bit - and every step of the way the codebase was
kept as stable as possible, fixing bugs and making sure all the tests passed.
When developing new features - things like erasure coding and snapshots -
write the minimal amount of code to get something that can be tested. Then,
add the minimal amount so you can ship it. Then ship it.
* Go the extra mile.
Before you send something out, try to put yourself in the shoes of someone
you know who writes really good code or who does really thorough code
reviews, and ask yourself what they'd do or ask for. Doing so before you send
out your patches is the quickest way to build trust and respect, and will
also lead to your patches moving to the top of the list of patches to review
and merge.
Lastly, I've made every effort to make bcachefs a solid base for others to build
off of, by making it as bug free as possible. Try to keep it that way, and pay
it forward to the people who came after you. At the same time, I'm only one
person, and I'm only human, so there's still lots of room for improvement. If
you see a way to refactor something that makes the code clearer or less fragile,
do it. The existing documentation isn't great - as you're learning the codebase,
that's a great opportunity to think of things that documentation should say, so
take those ideas and either write a bit of documentation yourself, or prod me
and get me to write it.
|
