You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@streams.apache.org by Matt Franklin <m....@gmail.com> on 2014/09/03 15:41:34 UTC
Re: Documentation & Testing
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 <ry...@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 <ss...@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 <ry...@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
> > >
> >
>
Re: Documentation & Testing
Posted by Renato Marroquín Mogrovejo <re...@gmail.com>.
Hi Ryan,
I think it is better to have anything established first and then keep on
improving the process because if not, then the project will just be full of
discussions and not progress.
Thanks and I will post anything through JIRA then :-)
Renato M.
On Sep 9, 2014 4:38 PM, "Ryan Ebanks" <ry...@gmail.com> wrote:
> 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 <ry...@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 <sb...@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
> > > > >> > >
> > > > >> >
> > > > >>
> > > >
> > >
> >
>
Re: Documentation & Testing
Posted by Ryan Ebanks <ry...@gmail.com>.
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 <ry...@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 <sb...@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 <ry...@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
> > > >> > >
> > > >> >
> > > >>
> > >
> >
>
Re: Documentation & Testing
Posted by Renato Marroquín Mogrovejo <re...@gmail.com>.
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 <ry...@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 <sb...@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....@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 <ry...@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 <ry...@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
> > >> > >
> > >> >
> > >>
> >
>
Re: Documentation & Testing
Posted by Ryan Ebanks <ry...@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 <sb...@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....@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 <ry...@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 <ss...@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 <ry...@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
> >> > >
> >> >
> >>
>
Re: Documentation & Testing
Posted by Steve Blackmon <sb...@apache.org>.
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....@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 <ry...@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 <ss...@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 <ry...@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
>> > >
>> >
>>