Hi Angie, thank you for answering the first third of my mail. I think we are not on the same page: in the last third I wrote explicit, that I know all the tools and places where to find informations - but i also mention that it is impossible to follow all relevant information. To lower the workload for us all we need a summery on a much higher level than CVS-messages (btw how many do we count a day - my estimation is two a minute). My request is for that higher level: For Core the policy and a handbook is avialable; but you can find modules in contrib that even don't have a README - sure you can go to the sourcecode and look what they do - but this is not efficient. The documentation is only the result of a process that happens before: the process of making decisions - this is what i want to discuss. Are you willing to give me a feedback what you understood? - Because I want to be sure we are on the same page. Best Thomas Am Donnerstag 06 November 2008 06:06:14 schrieb Angela Byron:
Yes I can read the code but the question above can not be answered by reading the code - much more helpful would be a comment what the _aim_ of some lines of code is.
And maybe the group working on and with that particular module has a list of decisions (not a mailinglist) and why they where made - so one could go back to the original decision (should be referenced in the code) and look up what the original intention was.
Do you agree that these information could help a lot in similar situaltions?
This is actually a feature built into CVS (and most other version control systems) called CVS Annotate that does exactly that: http://www.lullabot.com/articles/cvs_annotate_or_what_the_heck_were_they_th inking
For every line of code, you can discover who made the change, when they made it, and why. Assuming the maintainer is following standard commit message patterns, you can also reference the original issue that has all the background information on discussions on the code that were had, the development evolution of the feature over time, and why the decision was ultimately made to commit it.
It's a pretty awesome resource because it's automatically updated with every commit, without the need for any manual intervention or extra overhead.
-Angie