Hello, Just thought I''d make a remark regarding documentation. The submission process for patches doesn''t mention updating associated documentation (as far as I can see). This should also be a requirement along with test cases so that documentation stays up to date. If we''re planning on having good documention and we use the fund money to improve what we already have then we should make sure we try keep it that way. For example I just submitted a documentation patch (http://dev.rubyonrails.org/ticket/5762) for the :from option for the ActiveRecord find method. I''d think that adding support for this option should have had documentation associated with it when it was added to begin with. Just me 2 cents. Andrew
Andrew Kaspick wrote:> <snip> > > The submission process for patches doesn''t mention updating associated > documentation (as far as I can see). This should also be a > requirement along with test cases so that documentation stays up to > date. If we''re planning on having good documention and we use the > fund money to improve what we already have then we should make sure we > try keep it that way. > >I agree with this completely. The only way to guarantee an acceptable level of in code documentation is to require that code updates are accompanied by documentation updates, just as they are required to have test updates. Indeed, requiring documentation should make for better code as coders are forced to think more about their code from a user''s standpoint. Tom -- Tom Werner Helmets to Hardhats Software Developer tom@helmetstohardhats.org www.helmetstohardhats.org
On Aug 8, 2006, at 10:41 AM, Andrew Kaspick wrote:> The submission process for patches doesn''t mention updating associated > documentation (as far as I can see). This should also be a > requirement along with test cases so that documentation stays up to > date.+1 court3nay
I think at the moment it''s heavily encouraged that documenation be included with patches. What this turns out to mean commit side is that if your patch has associated documentation and tests included it''s significantly more likely that it will be commited. More people just need to know this (or take it seriously). -- Kevin Clark http://glu.ttono.us
Another good example that lacks documentation is behavior additions/changes. I.e.: the patch for has_one saving on create versus saving on update where it used to save on both. The new patch doesn''t do what I expect and I has to bug poor Jonathan to clarify what his expectations were on his patch (which he humored me and explained; thanks!). Kevin Clark wrote:> I think at the moment it''s heavily encouraged that documenation be > included with patches. What this turns out to mean commit side is that > if your patch has associated documentation and tests included it''s > significantly more likely that it will be commited. More people just > need to know this (or take it seriously). >
> For example I just submitted a documentation patch > (http://dev.rubyonrails.org/ticket/5762) for the :from option for the > ActiveRecord find method. I''d think that adding support for this > option should have had documentation associated with it when it was > added to begin with. > > Just me 2 cents.Trac could probably be updated to include this. But I certainly don''t apply patches which don''t have test cases *and* documentation. It''s already our process, but should probably make it explicit to save shotgun submitters some time. -- Cheers Koz
On Aug 8, 2006, at 3:47 PM, Michael Koziarski wrote:>> For example I just submitted a documentation patch >> (http://dev.rubyonrails.org/ticket/5762) for the :from option for the >> ActiveRecord find method. I''d think that adding support for this >> option should have had documentation associated with it when it was >> added to begin with. >> >> Just me 2 cents. > > Trac could probably be updated to include this. But I certainly > don''t apply patches which don''t have test cases *and* documentation. > It''s already our process, but should probably make it explicit to save > shotgun submitters some time.How about two new ticket resolutions: untested undocumented to put some shorelines our brimming, open sea? Anyone may resolve untested and undocumented tickets as such. Anyone may reopen when satisifed. Sprinkle with reports to assist those who want to team up either. jeremy (I considered ''unverified'' and ''unimplemented'' for bugs/patches too - maybe too much? :)
On Aug 8, 2006, at 4:43 PM, Jeremy Kemper wrote:> On Aug 8, 2006, at 3:47 PM, Michael Koziarski wrote: >>> For example I just submitted a documentation patch >>> (http://dev.rubyonrails.org/ticket/5762) for the :from option for >>> the >>> ActiveRecord find method. I''d think that adding support for this >>> option should have had documentation associated with it when it was >>> added to begin with. >>> >>> Just me 2 cents. >> >> Trac could probably be updated to include this. But I certainly >> don''t apply patches which don''t have test cases *and* documentation. >> It''s already our process, but should probably make it explicit to >> save >> shotgun submitters some time. > > > How about two new ticket resolutions: > > untested > > undocumented >Awesome!