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: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
