Matt - Great suggestion. We should get this all documented and added to the webpage with a general 'how to contribute' along with guidelines.
Steve - No testing should be 'testing just for the sake of having a test'. There needs to be tests to verify that the logic in all contributed code is correct/works as expected. At a minimum all public methods/functions should have tests. I also agree we need a users guide written. The documentation as a whole for this project is lacking, but I do feel that we will drastically be improving in this area shortly. -Ryan Ebanks On Wed, Sep 3, 2014 at 11:31 AM, Steve Blackmon <[email protected]> wrote: > Samza has excellent developer guidelines we could use for inspiration: > > http://samza.incubator.apache.org/contribute/rules.html > http://samza.incubator.apache.org/contribute/coding-guide.html > > I am in favor of testing, but skeptical of testing just for the sake > of having a test. How about someone take a shot at rules / coding > guide for streams, and we can discuss and tweak those documents until > they have sufficient support? > > P.S. > > We need to provide helpful documentation for implementers as well as > core developers. Personally I think this more important to increase > interest and adoption. > > I've found Spark's Programming Guide well-structured and useful. > > http://spark.apache.org/docs/latest/programming-guide.html > > Steve Blackmon > [email protected] > > On Wed, Sep 3, 2014 at 8:41 AM, Matt Franklin <[email protected]> > wrote: > > On the whole, I agree. I think it would be good to document this on the > > website. When we do, let's be sure to describe the best way to use GitHub > > (personal fork, etc) and what the minimum bar for UNIT testing is vs > > INTEGRATION tests. > > > > > > On Thu, Aug 28, 2014 at 4:09 PM, Ryan Ebanks <[email protected]> > wrote: > > > >> Stanton, > >> > >> I am on board with all of those suggestions. I know it may take some > time > >> to implement all of them, > >> but I agree we should start the discussion and start moving that > direction. > >> > >> > >> Hopefully the suggestions I proposed are just the first of many steps to > >> improving transparency > >> and quality in this project. > >> > >> -Ryan Ebanks > >> > >> > >> On Thu, Aug 28, 2014 at 3:54 PM, Stanton Sievers <[email protected]> > >> wrote: > >> > >> > Hey Ryan, > >> > > >> > I agree completely. I think there a few things that can be done on > top > >> of > >> > what you've proposed that can help make the need more transparent. > >> > > >> > Using maven site, we should be able to publish JavaDoc so it is > readily > >> > available for everyone to review and consume. > >> > > >> > Again, using maven site, we should be able to publish code coverage > >> > information to make it apparent where the gaps are and where folks > should > >> > focus their efforts to fill the gap. > >> > > >> > I'm not sure if there's a dedicated process for publishing maven site > to > >> an > >> > Apache's project's site, but that would be a good place to start if it > >> > exists. > >> > > >> > Also, at one point CloudBees offered free pull request building for > open > >> > source projects on BuildHive. This would allow a one-off build to be > >> > executed and evaluated against the pull request. If that build > reported > >> > code coverage information, it would help a reviewer establish whether > or > >> > not the level of unit testing is adequate. Even publishing this > >> > information as part of our own builds on builds.a.o would be useful. > >> > > >> > As a community we should have the discussion about the next steps, but > >> I'm > >> > hoping these options can get that conversation started. > >> > > >> > Thanks for bringing this up. > >> > -Stanton > >> > > >> > > >> > On Thu, Aug 28, 2014 at 4:18 PM, Ryan Ebanks <[email protected]> > >> wrote: > >> > > >> > > We need to do a better job of Documentation and Testing. Way too > many > >> > pull > >> > > requests are getting approved and merged in that contain no > >> documentation > >> > > and minimal or no testing. This needs to stop immediately. > >> > > > >> > > I know documentation and testing is time consuming and not fun, but > we > >> > > cannot push this off and hope someone will fix it the future. I am > >> > > proposing the following minimal guidelines/rules for all future pull > >> > > requests. > >> > > > >> > > *Documentation* > >> > > 1.) All pull requests contain adequate java docs > >> > > 2.) Java docs accurately reflect the code and are up to date > >> > > > >> > > *Testing* > >> > > 1.) Test must test more than 'does it throw an exception'. > (Most of > >> > the > >> > > serializers unit tests do exactly this) > >> > > For newly added classes > >> > > 1.) All classes have unit tests and integration tests (when > >> > > necessary) or it is explicitly stated in the pull request > >> why > >> > > that class can't/won't be tested. > >> > > For modifications to existing classes > >> > > 1.) Any method that you touch must have unit tests. If none > >> > > currently exist you are responsible for creating them. > >> > > > >> > > If any of these extremely minimal requirements are not met, your > pull > >> > > request will not be evaluated until it meets all of the > requirements. > >> > > *Anyone > >> > > evaluating a pull request should verify these requirements before > >> +1-ing > >> > > the request. All apache committers should verify that these > >> requirements > >> > > are met before merging requests too. * > >> > > > >> > > These basic steps will drastically improve our code base, and make > it > >> > > easier for the project to gain new contributors. > >> > > > >> > > Sincerely, > >> > > > >> > > Ryan Ebanks > >> > > > >> > > >> >
