New bcachefs contribution guideasciidoc

1 files changed, 113 insertions, 0 deletions

diff --git a/Contributing.mdwn b/Contributing.mdwn
new file mode 100644
index 0000000..bf41738
--- /dev/null
+++ b/Contributing.mdwn
@@ -0,0 +1,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.