[Vibrant Android Development] Genesis3:
Ok, this leads to the question: What was the provenance of the libaudio directory in vibrantmtd?

See, this is the problem. Yes, I looked at the commit chain originally; there was nothing that was dispositive.

Then I'll go looking for it. "You have to know where to look" is fine and well but the purpose of documentation is so people know where to look!

And this was posted in the bugtracker.... where? Ah, nowhere. Why is it so tough to include a link back to the commit(s) in question? How in the hell is someone supposed to figure out what was done and why if that's not there?

That's exactly my point -- there's a bare Clockwork ZIP file in the bugtracker with the statement "try this!" but no indication of what it is or where it came from. It's trivially easy, of course, to figure out that it's just libaudio.so, but there's nothing more.

This has been my issue from the beginning of attempting to work on this codebase -- there's a complete lack of the sort of tracking and documentation that has to be there in a codebase of this size (it takes several hours to pull a new copy with repo as I'm sure you know) if there's to be any reasonable ability for someone to come in and start being productive working on it in a reasonable amount of time. "You have to know where to look" isn't an acceptable answer when it's trivial to

state

where the code came from. When I say that you

are

hiding things that's exactly what I mean by it -- you just disclosed where the library came from but it would have been trivial to point at the commit when the zip file was posted. It was a

choice

not to.

Fine with me.

When I was working on the Triumph port I asked several questions related to code organization (things that should be documented in a way that's easy to find) and got silence in response. Literal silence. One of the more-mundane was about the light sensor and where that table definitions were for the lookup between light sensor and backlight; I wanted to fix the (very annoying) fact that the buttons were either on or off while the Triumph has PWM-controlled hardware and thus is entirely capable of allowing the user control over how bright those keys are lit. Fixing the kernel took me a few minutes. Figuring out the directory structure CM was using and how things worked under "overlay" in the device directory took several hours. How hard would it be to have a README at the top of the "device" directory documenting the layout of everything under there, the hierarchy, what gets picked up, overloaded and included from where and why? A far-more important example was with the RIL -- the Triumph has a screwball Qualcomm CDMA radio that likes to send asynchronous upcalls out for hardware it doesn't have (including claiming a non-existent RUIM is "not ready"), which was resetting the radio code. CM has modified the base RIL to branch it, but there's no documentation on exactly how and why it was done the way it was done (e.g RIL.java, SamsungRIL.java, etc) and how to extend your design cleanly within the code framework that you've already got. I tried to get answers to that so I could follow your conventions since I couldn't find any documentation in the code itself and again got silence. So I punted and made the changes to the base RIL.java file, casing them on a system.prop entry -- wrong, from a standpoint of integration, but it's either that or hack around for an unknown amount of time trying to figure out what ought to be written down so others can work within the code design you already have. I'm not going to submit that to gerrit because it's structurally wrong, but if nobody wants to document what's structurally

correct

what other option beyond re-learning that which you could have, and should have, documented what do you expect people to do?

Incidentally someone

else

committed code into RIL.java that arguably shouldn't be there either at some point in the past. There's a special-case in there for Samsung devices that is cased off a property entry -- when there's also a SamsungRIL.java! Why wasn't that code split off into the other file? Good question -- maybe because the person who wrote that bit of code couldn't figure out what the hell you did as it wasn't documented so

they

punted too? Hmmm....

A counter-example came with the MMS code. Inferiorhumanorgans had a set of patches to the MMS code for the Optimus; Virgin does some really odd things with the way they trigger MMS reception (unique to them as far as I know.) I asked what he had and he tossed back a link to the repo where he had made the changes by email. It took me a couple of hours to look at what he had, then integrate that into the Triumph codebase and test it. All done, nice and neat. Why hasn't that been submitted back into gerrit? Maybe for the same reason I didn't with the RIL -- I don't know what I'd break (if anything) with other devices by trying to do so, and while I can't speak for him it's quite possible that neither does he, and the reason is that there's

no documentation

as to how those pieces go together - not from Google or from CM.

Another example from the Triumph -- haptic feedback on the soft keys. It didn't work under CM7 and nobody seemed to know why. It turns out that the key definition has to be "VIRTUAL" in the keylayout file. But that flag is

undocumented

in the Android development guide! So how is someone supposed to divine that nice bit of information? This is a pox on Google's house, not yours, but the same point stands -- how the hell are people supposed to maintain something when the documentation is either wrong or missing and nobody will answer questions?

When I started working on the Vibrant I asked about documentation on the codebase that was in use. I got either half-answers or none at all from people inside CM, yet

someone

obviously does know (the device directory didn't magically appear on its own and neither did libaudio.) Again, the issue is no documentation. The assumption I made (yeah, I know, I got made an ass of by doing it too) was that the CM team overrode the default library set for the Vibrant for a good reason, but there were no answers as to WHY.

I'm not expecting anyone to bow to anybody. I do expect that if you want someone to contribute time and effort the "members" of your group will begin by not publicly and privately intentionally driving people off, slandering them and playing "stone wall" when questions are asked. If you're not going to document the codebase itself (and you should) then people have to be willing to answer questions because there's going to be a

lot

of them. The right way to do this is to make sure the documentation is there -- either in a README when it bears on an entire directory structure or either in the file or the commit -- and not a one-liner either unless it's instantly obvious from the two lines you changed what you were doing and why. "Pick up change from crespo" ISN'T, by the way, adequate unless you link back to the crespo commit where it's explained.

This is not a one-way street. I decided against merging the Triumph code and submitting it to gerrit for this reason; if CM wants to pull from my repos and merge it that's fine as they are public for the Triumph and will be here if I decide to run a split-off manifest for the Vibrant, but I'm not going to play an ego-driven game with a bunch of people who don't think that documenting what they do is important and neither is communicating when asked rather direct questions that arise as a direct consequence of their failure to document.

Another oddball example that bears directly on this issue is that the code support for "mangle" (technically "MSS clamping") in the kernel. Netd is missing it. But the "MANGLE" option is one that's quite old, actually, and is

necessary

in the kernel for tethering to work properly with any external interface that has a MSS smaller than 1500. Some do, particularly rmnet (as opposed to ppp) radio packet interfaces -- like the aforementioned Triumph's Qualcomm implementation. Here's the commit on it:

https://github.com/tickerguy/android_system_netd/commit/dccf7b64733e83c9df89c47bc9debeb31f644e07

It was surprising (and disturbing) to find that CM didn't bother picking this up a long time ago. It's a couple of line change, really, but is something that had kernel support for a long time. Without netd support the kernel's inclusion of it is worthless. Given how important many people find tethering to be you'd think this would have been in the base CM codebase a long time ago - but it's not.

I have a lot of code in the wild, including the akcs forum software that runs Tickerforum and my blog, that is very complex and yet I'd be embarrassed to release it as source. Not because the code structure sucks, but because I couldn't reasonably expect anyone other than me to understand it as the internal documentation either sucks or is non-existent. It would take you dozens of hours to go through akcs and figure out why I did what I did for some function and that code is a tiny fraction of the size of Android. Without documentation the time required to get a reasonable handle on the Android codebase is measured in months (or more), not hours or days. I have a reasonable feel around the framework and external portions of the codebase for CM at this point but every bit of it was garnered the hard way as pertinent documentation is simply absent.

The documentation state for Android just plain bites and CM's documentation state is no better. Google has done us all the disservice of withdrawing or failing to maintain much of the documentation leading to plenty of it being out of date, wrong or simply missing. "The code is the documentation" is a very pretty sentiment but when 90% of the comments in a code file are the copyright notice for Code Aurora at the top nobody who's ever done this sort of thing in a commercial context takes those claims seriously. CM is not alone in this regard -- the people who have done ICS ports have been similarly un-forthcoming as well. On the Triumph the irony was that Foxconn's kernel changes were the best-documented of anything in the codebase and all those "comments" amounted to, in most cases, a literal "FIH" tag!

At least you knew where to look by the presence of the tags even if there was no clue what the hell they were doing or why.

If you want me to maintain code I have to be able to ask questions and get timely answers if the docs are not there to support the software standing alone. That's the base requirement; everything else can probably be worked out, but that's not negotiable.

Absent that I'll do what I did on the Triumph.