+1. Ref Guide updates would be faster, easier and more accurate if there was more description of the changes introduced by each patch.
On Mon, Apr 13, 2015 at 5:43 AM, Shalin Shekhar Mangar < [email protected]> wrote: > +1 to everything. > > It is also nice to give more details into what changed between patches. > Unless you use review board, this is sometimes the only way to understand > the changes between two patches. Especially, please call out any hacks, > gotchas and todo items that you may have thought about when writing the > code. This is not just for people following the development but also for > future contributors who may have to debug your code and need some > historical context to understand the design decisions. Finally, if someone > has given you review comments, please be kind enough to point out if/how > they've been addressed. > > On Sun, Apr 12, 2015 at 12:21 AM, 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] >> >> > > > -- > Regards, > Shalin Shekhar Mangar. >
