streams-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ryan Ebanks <ryaneba...@gmail.com>
Subject Re: Documentation & Testing
Date Wed, 03 Sep 2014 18:52:22 GMT
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 <sblackmon@apache.org>
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
> sblackmon@apache.org
>
> On Wed, Sep 3, 2014 at 8:41 AM, Matt Franklin <m.ben.franklin@gmail.com>
> 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 <ryanebanks@gmail.com>
> 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 <ssievers@apache.org>
> >> 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 <ryanebanks@gmail.com>
> >> 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
> >> > >
> >> >
> >>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message