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 Tue, 09 Sep 2014 14:37:33 GMT
Renato,

I don't think we have really established a method for patching the website.
 That is something that we do need to discuss though, as we should be
generating documentation in the near term for the website. I think what you
have proposed is great for making changes to it now.

-Ryan Ebanks

On Tue, Sep 9, 2014 at 6:50 AM, Renato MarroquĂ­n Mogrovejo <
renatoj.marroquin@gmail.com> wrote:

> 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