Hey folks, I think Ryan has a good point here: http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html I''ll follow that up by saying that besides tests, there''s also a lot of documentation work that needs done too. Is there something we can do to improve the situation? What about having some kind of effort focused around writing JUST tests and docs that reaches out to the larger community? There are a bit over 50 days left before RailsConf - maybe we could have a contest or something during the leadup and then have some kind of award presented at the conference to whoever writes the most test/ docs. I''m not trying to make contributing into some kind of competitive thing, just brainstorming... If we could get a bunch of people to increase the test coverage, that would leave us in a better position to take on doing a stabilization/ performance/clean-up release. -- Josh Susser http://blog.hasmanythrough.com
I don''t understand this blog post. The graph looks more then healthy to me. On 4/26/06, Josh Susser <josh@hasmanythrough.com> wrote:> Hey folks, > > I think Ryan has a good point here: > http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html > > I''ll follow that up by saying that besides tests, there''s also a lot > of documentation work that needs done too. Is there something we can > do to improve the situation? > > What about having some kind of effort focused around writing JUST > tests and docs that reaches out to the larger community? There are a > bit over 50 days left before RailsConf - maybe we could have a > contest or something during the leadup and then have some kind of > award presented at the conference to whoever writes the most test/ > docs. I''m not trying to make contributing into some kind of > competitive thing, just brainstorming... > > If we could get a bunch of people to increase the test coverage, that > would leave us in a better position to take on doing a stabilization/ > performance/clean-up release. > > -- > Josh Susser > http://blog.hasmanythrough.com > > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core >-- Tobi http://shopify.com - modern e-commerce software http://typo.leetsoft.com - Open source weblog engine http://blog.leetsoft.com - Technical weblog
Regardless of whether Ryan''s graph is meaningful, I think doing a community push leading up to RailsConf would be great. I''d say the best way to do it would be to for someone to take the lead and just start driving it (by creating the tests and/or docs). Chad On Apr 26, 2006, at 7:57 AM, Tobias Lütke wrote:> I don''t understand this blog post. The graph looks more then > healthy to me. > > On 4/26/06, Josh Susser <josh@hasmanythrough.com> wrote: >> Hey folks, >> >> I think Ryan has a good point here: >> http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html >> >> I''ll follow that up by saying that besides tests, there''s also a lot >> of documentation work that needs done too. Is there something we can >> do to improve the situation? >> >> What about having some kind of effort focused around writing JUST >> tests and docs that reaches out to the larger community? There are a >> bit over 50 days left before RailsConf - maybe we could have a >> contest or something during the leadup and then have some kind of >> award presented at the conference to whoever writes the most test/ >> docs. I''m not trying to make contributing into some kind of >> competitive thing, just brainstorming... >> >> If we could get a bunch of people to increase the test coverage, that >> would leave us in a better position to take on doing a stabilization/ >> performance/clean-up release. >> >> -- >> Josh Susser >> http://blog.hasmanythrough.com >> >> >> _______________________________________________ >> Rails-core mailing list >> Rails-core@lists.rubyonrails.org >> http://lists.rubyonrails.org/mailman/listinfo/rails-core >> > > > -- > Tobi > http://shopify.com - modern e-commerce software > http://typo.leetsoft.com - Open source weblog engine > http://blog.leetsoft.com - Technical weblog > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core
Which parts of rails do you think need more documentation/tests? Are you talking about documentation for the internals of rails as well as the exposed APIs?>From the bits and pieces I''ve done with ActiveRecord I''ve been prettyimpressed with the test coverage. The docs on the inner workings are a bit non-existant, but the API docs are pretty good. -Jonathan. On 4/27/06, Josh Susser <josh@hasmanythrough.com> wrote:> > Hey folks, > > I think Ryan has a good point here: > http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html > > I''ll follow that up by saying that besides tests, there''s also a lot > of documentation work that needs done too. Is there something we can > do to improve the situation? > > What about having some kind of effort focused around writing JUST > tests and docs that reaches out to the larger community? There are a > bit over 50 days left before RailsConf - maybe we could have a > contest or something during the leadup and then have some kind of > award presented at the conference to whoever writes the most test/ > docs. I''m not trying to make contributing into some kind of > competitive thing, just brainstorming... > > If we could get a bunch of people to increase the test coverage, that > would leave us in a better position to take on doing a stabilization/ > performance/clean-up release. > > -- > Josh Susser > http://blog.hasmanythrough.com > > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core >_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
On 4/26/06, Jonathan Viney <jonathan.viney@gmail.com> wrote:> Which parts of rails do you think need more documentation/tests? Are you > talking about documentation for the internals of rails as well as the > exposed APIs? > > From the bits and pieces I''ve done with ActiveRecord I''ve been pretty > impressed with the test coverage. The docs on the inner workings are a bit > non-existant, but the API docs are pretty good. > > -Jonathan.Speaking from the perspective of a someone inexperienced with Rails and just starting to use it for legacy databases, I would love to see more docs and walkthroughs for the internals of ActiveRecord. - Rob -- http://www.robsanheim.com/ http://www.ajaxian.com
> I don''t understand this blog post. The graph looks more then healthy to me.I too could make little sense of the ramblings, but as Chad says, every day is a good day to improve documentation and test coverage. So I strongly encourage someone to take it upon themselves to either do a one-man raid for better documentation or gather up a team to work on it. -- David Heinemeier Hansson http://www.loudthinking.com -- Broadcasting Brain http://www.basecamphq.com -- Online project management http://www.backpackit.com -- Personal information manager http://www.rubyonrails.com -- Web-application framework
I think there could definitely be more documentation oriented towards internal development (routing is a good example of a poorly documented functionality). However, I think its premature to call for a mass refactoring of the code base, at this stage in development that would be akin to sending your new baby to a plastic surgeon to have a nose job and breast implants. Bob Silva http://www.railtie.net/ ________________________________________ From: rails-core-bounces@lists.rubyonrails.org [mailto:rails-core-bounces@lists.rubyonrails.org] On Behalf Of Jonathan Viney Sent: Wednesday, April 26, 2006 7:32 AM To: rails-core@lists.rubyonrails.org Subject: Re: [Rails-core] ganging up on tests and docs Which parts of rails do you think need more documentation/tests? Are you talking about documentation for the internals of rails as well as the exposed APIs?>From the bits and pieces I''ve done with ActiveRecord I''ve been prettyimpressed with the test coverage. The docs on the inner workings are a bit non-existant, but the API docs are pretty good. -Jonathan. On 4/27/06, Josh Susser <josh@hasmanythrough.com> wrote: Hey folks, I think Ryan has a good point here: http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html I''ll follow that up by saying that besides tests, there''s also a lot of documentation work that needs done too. Is there something we can do to improve the situation? What about having some kind of effort focused around writing JUST tests and docs that reaches out to the larger community? There are a bit over 50 days left before RailsConf - maybe we could have a contest or something during the leadup and then have some kind of award presented at the conference to whoever writes the most test/ docs. I''m not trying to make contributing into some kind of competitive thing, just brainstorming... If we could get a bunch of people to increase the test coverage, that would leave us in a better position to take on doing a stabilization/ performance/clean-up release. -- Josh Susser http://blog.hasmanythrough.com _______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
I think part of the problem is the docs on api.rubyonrails.org don''t include the whole Rails codebase. For example, the entire Rails "namespace" is excluded. The source files have comments and I imagine those can be published via RDoc - is there any reason to hide them? Justin _______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
On Apr 26, 2006, at 9:57 AM, Tobias Lütke wrote:> I don''t understand this blog post. The graph looks more then > healthy to me.The graph doesn''t mean much, really. It says that as the code LOC (measured by whatever he''s using to measure LOC) has increased, the test LOC has increased in roughly the same proportion, and that test LOC is some degree lower, in terms of LOC, than code LOC. I think what he''s driving at is that these lines should be converging rather than increasing at the same rate. Meaning we should be refactoring (lowering the code line) and adding more tests (increasing the test line). Or that when adding features, the test line rises at a greater rate than the code line. But, test:code LOC ratio doesn''t really mean anything. It indicates nothing about the coverage of the tests or the quality ("correctness") of the tests. It makes a big assumption that the writers of tests are creating perfect tests that cover all scenarios the test is intended to cover, and that''s never going to be the case, whether the tests are written by humans or generated automatically. There is no one metric for "test quality", there are several measurements that can be made. In the context of those other measurements, this graph might have meaning, perhaps it would demonstrate a correlation between code:test and coverage, but on its own it''s pretty pointless, and is just being used an excuse to rant about something. Of course we''ve got code that could use refactoring, of course there are areas that could use increased test coverage, and of course we could benefit from increased and clarified documentation. What project isn''t like that? I agree with Chad and strongly encourage folks to add documentation and test coverage. Everyone would benefit. A contest could be a neat idea if you can come up with some kind of metrics to determine a "winner", and that they are fair and published. -Scott
On Wed, Apr 26, 2006 at 08:22:26AM -0700, Justin Bailey wrote:> I think part of the problem is the docs on api.rubyonrails.org don''t > include the whole Rails codebase. For example, the entire Rails > "namespace" is excluded. The source files have comments and I imagine > those can be published via RDoc - is there any reason to hide them?As I see it, the reason to "hide" the internal api, from at least the main api documentation, is that there are far more people interested in working *with* Rails than there are people interested in working *on* Rails. For that 80 plus percent, having all the internal api docs mixed in with the external facing api would just be a huge jungle to sift through with a high noise ratio. There could be some value, indeed, in having a separate place one could go to get full documentation, including the internal api, but I don''t think it''s a good fit for the main api docs. marcel -- Marcel Molina Jr. <marcel@vernix.org>
I''ll take it. I''ll post on my blog about it tonight and get some sort of todo list so we can track who''s working on what docs/tests and try to get sd.rb in on the action (best way to learn about it is to have to write about it ;) ). Kev On 4/26/06, Scott Barron <scott@elitists.net> wrote:> > On Apr 26, 2006, at 9:57 AM, Tobias Lütke wrote: > > > I don''t understand this blog post. The graph looks more then > > healthy to me. > > The graph doesn''t mean much, really. It says that as the code LOC > (measured by whatever he''s using to measure LOC) has increased, the > test LOC has increased in roughly the same proportion, and that test > LOC is some degree lower, in terms of LOC, than code LOC. > > I think what he''s driving at is that these lines should be converging > rather than increasing at the same rate. Meaning we should be > refactoring (lowering the code line) and adding more tests > (increasing the test line). Or that when adding features, the test > line rises at a greater rate than the code line. > > But, test:code LOC ratio doesn''t really mean anything. It indicates > nothing about the coverage of the tests or the quality > ("correctness") of the tests. It makes a big assumption that the > writers of tests are creating perfect tests that cover all scenarios > the test is intended to cover, and that''s never going to be the case, > whether the tests are written by humans or generated automatically. > > There is no one metric for "test quality", there are several > measurements that can be made. In the context of those other > measurements, this graph might have meaning, perhaps it would > demonstrate a correlation between code:test and coverage, but on its > own it''s pretty pointless, and is just being used an excuse to rant > about something. > > Of course we''ve got code that could use refactoring, of course there > are areas that could use increased test coverage, and of course we > could benefit from increased and clarified documentation. What > project isn''t like that? > > I agree with Chad and strongly encourage folks to add documentation > and test coverage. Everyone would benefit. A contest could be a > neat idea if you can come up with some kind of metrics to determine a > "winner", and that they are fair and published. > > -Scott > > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core >
Are there any Ruby projects out there that show test coverage versus lines of code? Similar to the Java world''s Clover, JCover, or JLint? Something that could aid in showing where test coverage is "light"? Is there a Ruby way to track common metrics like Cyclomatic Complexity or does the dynamic nature of Ruby make this inherently impossible™? On 4/26/06, Kevin Clark <kevin.clark@gmail.com> wrote:> > I''ll take it. I''ll post on my blog about it tonight and get some sort > of todo list so we can track who''s working on what docs/tests and try > to get sd.rb in on the action (best way to learn about it is to have > to write about it ;) ). > Kev > > On 4/26/06, Scott Barron <scott@elitists.net> wrote: > > > > On Apr 26, 2006, at 9:57 AM, Tobias Lütke wrote: > > > > > I don''t understand this blog post. The graph looks more then > > > healthy to me. > > > > The graph doesn''t mean much, really. It says that as the code LOC > > (measured by whatever he''s using to measure LOC) has increased, the > > test LOC has increased in roughly the same proportion, and that test > > LOC is some degree lower, in terms of LOC, than code LOC. > > > > I think what he''s driving at is that these lines should be converging > > rather than increasing at the same rate. Meaning we should be > > refactoring (lowering the code line) and adding more tests > > (increasing the test line). Or that when adding features, the test > > line rises at a greater rate than the code line. > > > > But, test:code LOC ratio doesn''t really mean anything. It indicates > > nothing about the coverage of the tests or the quality > > ("correctness") of the tests. It makes a big assumption that the > > writers of tests are creating perfect tests that cover all scenarios > > the test is intended to cover, and that''s never going to be the case, > > whether the tests are written by humans or generated automatically. > > > > There is no one metric for "test quality", there are several > > measurements that can be made. In the context of those other > > measurements, this graph might have meaning, perhaps it would > > demonstrate a correlation between code:test and coverage, but on its > > own it''s pretty pointless, and is just being used an excuse to rant > > about something. > > > > Of course we''ve got code that could use refactoring, of course there > > are areas that could use increased test coverage, and of course we > > could benefit from increased and clarified documentation. What > > project isn''t like that? > > > > I agree with Chad and strongly encourage folks to add documentation > > and test coverage. Everyone would benefit. A contest could be a > > neat idea if you can come up with some kind of metrics to determine a > > "winner", and that they are fair and published. > > > > -Scott > > > > > > _______________________________________________ > > Rails-core mailing list > > Rails-core@lists.rubyonrails.org > > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core >_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
On Apr 26, 2006, at 8:50 AM, Kevin Clark wrote:> I''ll take it. I''ll post on my blog about it tonight and get some sort > of todo list so we can track who''s working on what docs/tests and try > to get sd.rb in on the action (best way to learn about it is to have > to write about it ;) ). > KevThat''s great, Kevin. I''m happy to help out, just let me know if you need a hand with any of that. I have a little list of places where the docs need some work that I can dump into the todo list. You can email me off the list if you have anything I can help with. Is it a crazy idea to think that Basecamp might be useful for this effort? :-) On Apr 26, 2006, at 8:44 AM, Marcel Molina Jr. wrote:> There could be some value, indeed, in having a separate place one > could go to > get full documentation, including the internal api, but I don''t > think it''s a > good fit for the main api docs.I agree, and I also agree there''s value in having the internal API, though just beefing up and correcting comments in the sources would help considerably. "Every comment is a lie waiting to happen." -- Alex Chaffee -- Josh Susser http://blog.hasmanythrough.com
Hello Steve, 2006/4/26, Steve Longdo <steve.longdo@gmail.com>:> Are there any Ruby projects out there that show test coverage versus > lines of code? Similar to the Java world's Clover, JCover, or JLint? > Something that could aid in showing where test coverage is "light"?Maybe you could have a look at rcov : http://eigenclass.org/hiki.rb?rcov -- Jean-François. -- À la renverse. _______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
On 4/26/06, Josh Susser <josh@hasmanythrough.com> wrote:> That''s great, Kevin. I''m happy to help out, just let me know if you > need a hand with any of that. I have a little list of places where > the docs need some work that I can dump into the todo list. You can > email me off the list if you have anything I can help with.Josh, awesome.> > Is it a crazy idea to think that Basecamp might be useful for this > effort? :-)It might be useful :) I was thinking about using Writeboard for the revisions, but I think the textile formatting would interfere with the rdoc and confuse things. It''d still be nice to look at changes. Maybe we can hack something up similar. Trac also may be the way to go, where people submit documentation tickets back. I do think a hurdle for those who want to contribute (but may not have the know how) is the process of checking out trunk. It''d be nice if we could streamline accessing the documentation and making diffs, but that''s really just for the wishlist.
Oh, and on the test side the main trac is probably the way to go. Maybe we should standardize "testing" as a tag for patches adding tests/testing support? Kev On 4/26/06, Kevin Clark <kevin.clark@gmail.com> wrote:> On 4/26/06, Josh Susser <josh@hasmanythrough.com> wrote: > > > That''s great, Kevin. I''m happy to help out, just let me know if you > > need a hand with any of that. I have a little list of places where > > the docs need some work that I can dump into the todo list. You can > > email me off the list if you have anything I can help with. > > Josh, awesome. > > > > > Is it a crazy idea to think that Basecamp might be useful for this > > effort? :-) > > It might be useful :) I was thinking about using Writeboard for the > revisions, but I think the textile formatting would interfere with the > rdoc and confuse things. It''d still be nice to look at changes. Maybe > we can hack something up similar. Trac also may be the way to go, > where people submit documentation tickets back. > > I do think a hurdle for those who want to contribute (but may not have > the know how) is the process of checking out trunk. It''d be nice if we > could streamline accessing the documentation and making diffs, but > that''s really just for the wishlist. >
Insurance docs mention a problem with loading test/mocks in Rails so rcov it is... I did find a project on Rubyforge called Saikuro ( http://rubyforge.org/projects/saikuro/ ) for getting CC metrics on Ruby code, but it hasn''t had any activity for a while. I''ll try out RCOV tonight on Rails and see what happens. I''ll report my findings back to the list or post them online. Thanks, -Steve On 4/26/06, Jean-François <jf.web3@gmail.com> wrote:> > Hello Steve, > > 2006/4/26, Steve Longdo <steve.longdo@gmail.com>: > > Are there any Ruby projects out there that show test coverage versus > > lines of code? Similar to the Java world''s Clover, JCover, or JLint? > > Something that could aid in showing where test coverage is "light"? > > Maybe you could have a look at rcov : > > http://eigenclass.org/hiki.rb?rcov > > -- Jean-François. > > -- > À la renverse. > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > >_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
On Wed, Apr 26, 2006 at 06:13:46PM +0200, Jean-Fran??ois wrote:> Hello Steve, > > 2006/4/26, Steve Longdo <steve.longdo@gmail.com>: > > Are there any Ruby projects out there that show test coverage versus > > lines of code? Similar to the Java world''s Clover, JCover, or JLint? > > Something that could aid in showing where test coverage is "light"? > > Maybe you could have a look at rcov : > > http://eigenclass.org/hiki.rb?rcovThere is also Insurance: http://insurance.rubyforge.org/ marcel -- Marcel Molina Jr. <marcel@vernix.org>
I ran rcov against Typo''s functional tests with: rcov test/functionals/*.rb It shows some Rails coverage as well (from the vendors directory). I put the results online at http://www.stevelongdo.com/typo/coverage/ My work computer is a windows box that is for *gulp* Java development. So I don''t have sparklines installed for example so the lack of coverage shown on the graphs for sparklines stuff is because of my lame-o work PC. I will try out against Rails test suites on OS X/Mac tonight at home. I will also extract the CSS info out of rcov so it can be styled independently (that 68% sized text is hard to read). Is there any simple way to run rails tests without using rake test? I now that I can point rcov at individual rb files, but I wondered if there is some sort of "Rails master test" rb file that excercises the actionpack, activerecord, actionmailer, actionwebservice, activesupport, and railties projects? On 4/26/06, Steve Longdo <steve.longdo@gmail.com> wrote:> > Insurance docs mention a problem with loading test/mocks in Rails so rcov > it is... > > I did find a project on Rubyforge called Saikuro ( http://rubyforge.org/projects/saikuro/ > ) for getting CC metrics on Ruby code, but it hasn''t had any activity for > a while. > > I''ll try out RCOV tonight on Rails and see what happens. I''ll report my > findings back to the list or post them online. > > Thanks, > -Steve > > On 4/26/06, Jean-François <jf.web3@gmail.com> wrote: > > > Hello Steve, > > 2006/4/26, Steve Longdo <steve.longdo@gmail.com>: > > Are there any Ruby projects out there that show test coverage versus > > lines of code? Similar to the Java world''s Clover, JCover, or JLint? > > Something that could aid in showing where test coverage is "light"? > > Maybe you could have a look at rcov : > > http://eigenclass.org/hiki.rb?rcov > > -- Jean-François. > > -- > À la renverse. > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > >_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
Hey man, I''m up for helping with the docs. My vote: RJS docs. Once you get a list up, make sure to pass the link out here. "Let''s get it on!" (TM) -hampton. On 4/26/06, Kevin Clark <kevin.clark@gmail.com> wrote:> > I''ll take it. I''ll post on my blog about it tonight and get some sort > of todo list so we can track who''s working on what docs/tests and try > to get sd.rb in on the action (best way to learn about it is to have > to write about it ;) ). > Kev > > On 4/26/06, Scott Barron <scott@elitists.net> wrote: > > > > On Apr 26, 2006, at 9:57 AM, Tobias Lütke wrote: > > > > > I don''t understand this blog post. The graph looks more then > > > healthy to me. > > > > The graph doesn''t mean much, really. It says that as the code LOC > > (measured by whatever he''s using to measure LOC) has increased, the > > test LOC has increased in roughly the same proportion, and that test > > LOC is some degree lower, in terms of LOC, than code LOC. > > > > I think what he''s driving at is that these lines should be converging > > rather than increasing at the same rate. Meaning we should be > > refactoring (lowering the code line) and adding more tests > > (increasing the test line). Or that when adding features, the test > > line rises at a greater rate than the code line. > > > > But, test:code LOC ratio doesn''t really mean anything. It indicates > > nothing about the coverage of the tests or the quality > > ("correctness") of the tests. It makes a big assumption that the > > writers of tests are creating perfect tests that cover all scenarios > > the test is intended to cover, and that''s never going to be the case, > > whether the tests are written by humans or generated automatically. > > > > There is no one metric for "test quality", there are several > > measurements that can be made. In the context of those other > > measurements, this graph might have meaning, perhaps it would > > demonstrate a correlation between code:test and coverage, but on its > > own it''s pretty pointless, and is just being used an excuse to rant > > about something. > > > > Of course we''ve got code that could use refactoring, of course there > > are areas that could use increased test coverage, and of course we > > could benefit from increased and clarified documentation. What > > project isn''t like that? > > > > I agree with Chad and strongly encourage folks to add documentation > > and test coverage. Everyone would benefit. A contest could be a > > neat idea if you can come up with some kind of metrics to determine a > > "winner", and that they are fair and published. > > > > -Scott > > > > > > _______________________________________________ > > Rails-core mailing list > > Rails-core@lists.rubyonrails.org > > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core >_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
Ok, the deal at this point is that when you have a doc patch, when you add the ticket make sure to add the ''docs'' patch. It will then show up in the documentation report on trac (http://dev.rubyonrails.org/report/20) and it can be reviewed and checked in. Go add docs! Kev On 4/26/06, Hampton <hcatlin@gmail.com> wrote:> Hey man, I''m up for helping with the docs. > > My vote: RJS docs. > > Once you get a list up, make sure to pass the link out here. > > "Let''s get it on!" (TM) > > -hampton. > > > On 4/26/06, Kevin Clark <kevin.clark@gmail.com> wrote: > > I''ll take it. I''ll post on my blog about it tonight and get some sort > > of todo list so we can track who''s working on what docs/tests and try > > to get sd.rb in on the action (best way to learn about it is to have > > to write about it ;) ). > > Kev > > > > On 4/26/06, Scott Barron <scott@elitists.net> wrote: > > > > > > On Apr 26, 2006, at 9:57 AM, Tobias Lütke wrote: > > > > > > > I don''t understand this blog post. The graph looks more then > > > > healthy to me. > > > > > > The graph doesn''t mean much, really. It says that as the code LOC > > > (measured by whatever he''s using to measure LOC) has increased, the > > > test LOC has increased in roughly the same proportion, and that test > > > LOC is some degree lower, in terms of LOC, than code LOC. > > > > > > I think what he''s driving at is that these lines should be converging > > > rather than increasing at the same rate. Meaning we should be > > > refactoring (lowering the code line) and adding more tests > > > (increasing the test line). Or that when adding features, the test > > > line rises at a greater rate than the code line. > > > > > > But, test:code LOC ratio doesn''t really mean anything. It indicates > > > nothing about the coverage of the tests or the quality > > > ("correctness") of the tests. It makes a big assumption that the > > > writers of tests are creating perfect tests that cover all scenarios > > > the test is intended to cover, and that''s never going to be the case, > > > whether the tests are written by humans or generated automatically. > > > > > > There is no one metric for "test quality", there are several > > > measurements that can be made. In the context of those other > > > measurements, this graph might have meaning, perhaps it would > > > demonstrate a correlation between code:test and coverage, but on its > > > own it''s pretty pointless, and is just being used an excuse to rant > > > about something. > > > > > > Of course we''ve got code that could use refactoring, of course there > > > are areas that could use increased test coverage, and of course we > > > could benefit from increased and clarified documentation. What > > > project isn''t like that? > > > > > > I agree with Chad and strongly encourage folks to add documentation > > > and test coverage. Everyone would benefit. A contest could be a > > > neat idea if you can come up with some kind of metrics to determine a > > > "winner", and that they are fair and published. > > > > > > -Scott > > > > > > > > > _______________________________________________ > > > Rails-core mailing list > > > Rails-core@lists.rubyonrails.org > > > > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > > > _______________________________________________ > > Rails-core mailing list > > Rails-core@lists.rubyonrails.org > > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > >
Damn it.. that''s add the ''docs'' keyword to your patch. Kev On 4/26/06, Kevin Clark <kevin.clark@gmail.com> wrote:> Ok, the deal at this point is that when you have a doc patch, when you > add the ticket make sure to add the ''docs'' patch. It will then show up > in the documentation report on trac > (http://dev.rubyonrails.org/report/20) and it can be reviewed and > checked in. > > Go add docs! > Kev > > On 4/26/06, Hampton <hcatlin@gmail.com> wrote: > > Hey man, I''m up for helping with the docs. > > > > My vote: RJS docs. > > > > Once you get a list up, make sure to pass the link out here. > > > > "Let''s get it on!" (TM) > > > > -hampton. > > > > > > On 4/26/06, Kevin Clark <kevin.clark@gmail.com> wrote: > > > I''ll take it. I''ll post on my blog about it tonight and get some sort > > > of todo list so we can track who''s working on what docs/tests and try > > > to get sd.rb in on the action (best way to learn about it is to have > > > to write about it ;) ). > > > Kev > > > > > > On 4/26/06, Scott Barron <scott@elitists.net> wrote: > > > > > > > > On Apr 26, 2006, at 9:57 AM, Tobias Lütke wrote: > > > > > > > > > I don''t understand this blog post. The graph looks more then > > > > > healthy to me. > > > > > > > > The graph doesn''t mean much, really. It says that as the code LOC > > > > (measured by whatever he''s using to measure LOC) has increased, the > > > > test LOC has increased in roughly the same proportion, and that test > > > > LOC is some degree lower, in terms of LOC, than code LOC. > > > > > > > > I think what he''s driving at is that these lines should be converging > > > > rather than increasing at the same rate. Meaning we should be > > > > refactoring (lowering the code line) and adding more tests > > > > (increasing the test line). Or that when adding features, the test > > > > line rises at a greater rate than the code line. > > > > > > > > But, test:code LOC ratio doesn''t really mean anything. It indicates > > > > nothing about the coverage of the tests or the quality > > > > ("correctness") of the tests. It makes a big assumption that the > > > > writers of tests are creating perfect tests that cover all scenarios > > > > the test is intended to cover, and that''s never going to be the case, > > > > whether the tests are written by humans or generated automatically. > > > > > > > > There is no one metric for "test quality", there are several > > > > measurements that can be made. In the context of those other > > > > measurements, this graph might have meaning, perhaps it would > > > > demonstrate a correlation between code:test and coverage, but on its > > > > own it''s pretty pointless, and is just being used an excuse to rant > > > > about something. > > > > > > > > Of course we''ve got code that could use refactoring, of course there > > > > are areas that could use increased test coverage, and of course we > > > > could benefit from increased and clarified documentation. What > > > > project isn''t like that? > > > > > > > > I agree with Chad and strongly encourage folks to add documentation > > > > and test coverage. Everyone would benefit. A contest could be a > > > > neat idea if you can come up with some kind of metrics to determine a > > > > "winner", and that they are fair and published. > > > > > > > > -Scott > > > > > > > > > > > > _______________________________________________ > > > > Rails-core mailing list > > > > Rails-core@lists.rubyonrails.org > > > > > > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > > > > > _______________________________________________ > > > Rails-core mailing list > > > Rails-core@lists.rubyonrails.org > > > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > > > > > >
> As I see it, the reason to "hide" the internal api, from at least the main > api documentation, is that there are far more people interested in working > *with* Rails than there are people interested in working *on* Rails. For that > 80 plus percent, having all the internal api docs mixed in with the external > facing api would just be a huge jungle to sift through with a high noise > ratio. > > There could be some value, indeed, in having a separate place one could go to > get full documentation, including the internal api, but I don''t think it''s a > good fit for the main api docs.Further to this, we''ve always said "If it isn''t documented, then it may change in the next release". There''s probably a good case for some articles explaining the internals of rails, as it makes it easier for people to submit patches, and improves the quality of the patches, making them easier to apply. But if we document something in the API docs, people will use it. If people use it, we can''t change it without breaking their apps. -- Cheers Koz
On Apr 26, 2006, at 2:49 PM, Michael Koziarski wrote:>> As I see it, the reason to "hide" the internal api, from at least >> the main >> api documentation, is that there are far more people interested in >> working >> *with* Rails than there are people interested in working *on* >> Rails. For that >> 80 plus percent, having all the internal api docs mixed in with >> the external >> facing api would just be a huge jungle to sift through with a high >> noise >> ratio. >> >> There could be some value, indeed, in having a separate place one >> could go to >> get full documentation, including the internal api, but I don''t >> think it''s a >> good fit for the main api docs. > > Further to this, we''ve always said "If it isn''t documented, then it > may change in the next release". There''s probably a good case for > some articles explaining the internals of rails, as it makes it easier > for people to submit patches, and improves the quality of the patches, > making them easier to apply. > > But if we document something in the API docs, people will use it. If > people use it, we can''t change it without breaking their apps.I don''t think the presence or absence of documentation ought to indicate whether or not an API is published. The published API is carved in stone. Any other API is subject to change without notice. As long as we indicate which are part of the published API and which are not, we''re fine. Regardless, lack of documentation is a bad thing, for any level of the API. - Jamis
Isn''t having to read the source code for methods A, B, C, and D to figure out what method E does part of the fun? Jokes aside, I absolutely agree. I do think non-public (and non-generated) documentation would be extremely helpful. Often times it is a bit confusing reading the source code if there isn''t a bit of a help. So writing comments on methods which are :nodoc: is still useful to those who are digging into the code for the first time or doing plugins. Someone writing a plugin might want to use something that''s a bit more low level to keep their plugin as dry as possible and we should encourage that. Having an active documentation writing spree as is suggested in this thread is absolutely a good idea for the public documentation. What I am suggesting is that we focus on this... If you change an "inner" method, write a line or two of method documentation. Just, while you''re there writing your patch for some else, just snap in a few programmers notes. If we all do that passively as we work on other stuff, then eventually we will have some smashingly good internal documentation for the project. Thoughts? -hampton On 4/26/06, Jamis Buck <jamis@37signals.com> wrote:> > I don''t think the presence or absence of documentation ought to > indicate whether or not an API is published. The published API is > carved in stone. Any other API is subject to change without notice. > > As long as we indicate which are part of the published API and which > are not, we''re fine. > > Regardless, lack of documentation is a bad thing, for any level of > the API. > > - Jamis > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core >_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
David Heinemeier Hansson wrote : | > I don''t understand this blog post. The graph looks more then healthy to me. | | I too could make little sense of the ramblings, but as Chad says, | every day is a good day to improve documentation and test coverage. So | I strongly encourage someone to take it upon themselves to either do a | one-man raid for better documentation or gather up a team to work on | it. On a side note, there also some ''more than simple to fix'' problems regarding the way documentation is formated (sometimes it''s just because a block of doc is not preoperly indented to transform it into verbatim). I wrote several patches regarding these but so far it seems that none have been integrated. Perhaps that having a separate trac category for this kind of fixes would help in order to sort out these simple patches. -- Frederick Ros aka Sleeper -- sleeper@jabber.fr ..you could spend *all day* customizing the title bar. Believe me. I speak from experience." (By Matt Welsh) _______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
Frederick, Please tag your documentations patches with the ''docs'' keyword and make sure they have [PATCH] in front of them, and we''ll take a look. Thanks! Kev On 4/27/06, Frederick Ros <sl33p3r@free.fr> wrote:> David Heinemeier Hansson wrote : > | > I don''t understand this blog post. The graph looks more then healthy to me. > | > | I too could make little sense of the ramblings, but as Chad says, > | every day is a good day to improve documentation and test coverage. So > | I strongly encourage someone to take it upon themselves to either do a > | one-man raid for better documentation or gather up a team to work on > | it. > > On a side note, there also some ''more than simple to fix'' problems > regarding the way documentation is formated (sometimes it''s just because > a block of doc is not preoperly indented to transform it into > verbatim). > > I wrote several patches regarding these but so far it seems that none > have been integrated. Perhaps that having a separate trac category for > this kind of fixes would help in order to sort out these simple patches. > > -- > Frederick Ros aka Sleeper -- sleeper@jabber.fr > > ..you could spend *all day* customizing the title bar. Believe me. I > speak from experience." > (By Matt Welsh) > > > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core > > > >
Kevin Clark wrote :
| Frederick,
| Please tag your documentations patches with the ''docs''
keyword and
| make sure they have [PATCH] in front of them, and we''ll take a look.
Wow ! That was quick ... As soon as I added the keyword you made it !
Thanks a lot ... I''m going to see if I can add some documentation for
methods that need some, beginning with some easy ones.
Best Regards,
--
Frederick Ros aka Sleeper -- sleeper@jabber.fr
Don''t sacrifice clarity for small gains in "efficiency".
- The Elements of Programming Style (Kernighan & Plaugher)
_______________________________________________
Rails-core mailing list
Rails-core@lists.rubyonrails.org
http://lists.rubyonrails.org/mailman/listinfo/rails-core
> Wow ! That was quick ... As soon as I added the keyword you made it ! > Thanks a lot ... I''m going to see if I can add some documentation for > methods that need some, beginning with some easy ones.Awesome. Thanks for the patch. Also, thanks to Marcel for helping get this stuff commited. Kev
On 4/26/06, Josh Susser <josh@hasmanythrough.com> wrote:> Hey folks, > > I think Ryan has a good point here: > http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html > > I''ll follow that up by saying that besides tests, there''s also a lot > of documentation work that needs done too. Is there something we can > do to improve the situation?PHP style docs website with user comments please:)
> PHP style docs website with user comments please:)There''s definitely something in that suggestion. More generally, the docs are often consulted immediately, and in turn might prompt the developer to look for applied, expanded or more up- to-date resources (wiki / manuals / blogs / etc). In this sense, we can view the api docs as something of a springboard / portal. This might suggest a number of other ideas, such as a Rollyo search bar for Rails material [*] in the documentation page header. Or, a list of wiki articles which relate to the current documentation topic, somewhere on the page. Any other ideas? * - eg http://rollyo.com/goldenv/ruby_rails_resources/ cheers, David On 30/04/2006, at 1:18 AM, Peter Michaux wrote:> On 4/26/06, Josh Susser <josh@hasmanythrough.com> wrote: >> Hey folks, >> >> I think Ryan has a good point here: >> http://blog.zenspider.com/archives/2006/04/where_is_our_ma.html >> >> I''ll follow that up by saying that besides tests, there''s also a lot >> of documentation work that needs done too. Is there something we can >> do to improve the situation? > > PHP style docs website with user comments please:) > _______________________________________________ > Rails-core mailing list > Rails-core@lists.rubyonrails.org > http://lists.rubyonrails.org/mailman/listinfo/rails-core