Great advise; thanks Yonik. ~ David Smiley Freelance Apache Lucene/Solr Search Consultant/Developer http://www.linkedin.com/in/davidwsmiley
On Sat, Apr 11, 2015 at 2:51 PM, Yonik Seeley <[email protected]> wrote: > Devs & contributors, please remember to be nice to other contributors > and describe what your patch is trying to do in the JIRA issue. > > For patches that add/change an API, that means giving an example or > specifying what the API is. People should not have to read through > source code to try and reconstruct what an API actually looks like in > order to give feedback on a proposed API. > > Also, for CHANGES, please consider what it will take for others to > understand the actual change. Don't automatically just use the JIRA > description. > - if you added a new parameter, then put that parameter in the description > - where appropriate, put a short/concise example (not more than a few > lines though) - when to do this is more subjective, but please think > about it for very commonly used APIs. > > > For the sake of example, I'll pick on the first feature added for 5.2: > > from CHANGES.txt: > ''' > New Features > ---------------------- > * SOLR-6637: Solr should have a way to restore a core from a backed up > index. > ''' > > So it's saying we *should* have a feature (as opposed to saying we > actually now do have a feature, and what that feature is), and doesn't > give you any clue how that feature was actually implemented, or how > you could go about finding out. > > So next, I go to SOLR-6637 to try and see what this feature actually > consists of. > Unfortunately, there's never an example of how someone is supposed to > try this feature out. We're setting a high bar for contribution from > others. > > So next, I use the source to try and reconstruct what the API actually > looks like. > I find what looks like will be the right test class: > > https://svn.apache.org/viewvc/lucene/dev/trunk/solr/core/src/test/org/apache/solr/handler/TestRestoreCore.java?view=markup > > Of course, the tests aren't going to directly give me what a command > URL would look like, but this is the closest thing: > TestReplicationHandlerBackup.runBackupCommand(masterJetty, > ReplicationHandler.CMD_RESTORE, params); > > And continue following the source just to be able to construct a > simple example like I gave here: > > http://yonik.com/solr-5-2/ > > (so I finally tried it out, and it works... yay ;-) > > So to recap: > - Consider CHANGES documentation. > - Describe *what* you are trying to implement in your JIRA issues, and > give API examples where appropriate. > > -Yonik > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
