From 8a9595765da75451f00422905ce9ebc417c90c84 Mon Sep 17 00:00:00 2001 From: Kent Overstreet Date: Fri, 27 Apr 2018 16:49:39 -0400 Subject: New bcachefs contribution guide --- Contributing.mdwn | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 Contributing.mdwn 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. -- cgit v1.2.3