streams-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Renato MarroquĂ­n Mogrovejo <renatoj.marroq...@gmail.com>
Subject Re: Documentation & Testing
Date Tue, 09 Sep 2014 11:50:52 GMT
Hi Ryan,

The project really needs this. But how can we propose patches for the
website? I remember I had some troubles in setting the project initially,
and found some problems with the website, and I wanted to change them, but
I didn't find an easy way of doing this other than opening a JIRA and
posting a patch for the specific change. If everyone is ok with than, then
I will do that for fixing some errors  :)


Renato M.

2014-09-03 20:52 GMT+02:00 Ryan Ebanks <ryanebanks@gmail.com>:

> 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