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 < [email protected]> 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 <[email protected]>: > > > 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 > > > >> > > > > > >> > > > > >> > > > > > >
