Marvin, thank you for taking the time to write up this great guidelines. Would you mind adding this to the wiki? I think this is very valuable for new devs and contributors.
simon On Thu, Mar 4, 2010 at 6:28 PM, Marvin Humphrey <mar...@rectangular.com> wrote: > (CC to lucy-dev and general, reply-to set to general) > > On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote: > >> (Warning, this post is long, and is easier to read in JIRA) > > I consume email from many of the Lucene lists, and I hate it when people force > me to read stuff via JIRA. It slows me down to have to jump to all those > forum web pages. I only go the web page if there are 5 or more posts in a row > on the same issue that I need to read. > > For what it's worth, I've worked out a few routines that make it possible to > compose messages which read well in both mediums. > > * Never edit your posts unless absolutely necessary. If JIRA used diffs, > things would be different, but instead it sends the whole frikkin' post > twice (before and after), which makes it very difficult to see what was > edited. If you must edit, append an "edited:" block at the end to > describe what you changed instead of just making changes inline. > * Use FireFox and the "It's All Text" plugin, which makes it possible to edit > JIRA posts using an external editor such as Vim instead of typing into a > textarea. <http://trac.gerf.org/itsalltext> > * After editing, use the preview button (it's a little monitor icon to the > upper right of the textarea) to make sure the post looks good in JIRA. > * Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's > mechanisms look so crappy in email. This is easy from Vim, because > rewrapping a long line (by typing "gq" from visual mode to rewrap the > current selection) that starts with "> " causes "> " to be prepended to > the wrapped lines. > * Use asterisk bullet lists liberally, because they look good everywhere. > * Use asterisks for *emphasis*, because that looks good everywhere. > * If you wrap lines, use a reasonably short line length. (I use 78; Mike > McCandless, who also wraps lines for his Jira posts, uses a smaller > number). Otherwise you'll get nasty wrapping in narrow windows, both in > email clients and web browsers. > > There are still a couple compromises that don't work out well. For email, > ideally you want to set off code blocks with indenting: > > int foo = 1; > int bar = 2; > > To make code look decent in JIRA, you have to wrap that with {code} tags, > which unfortunately look heinous in email. Left-justifying the tags but > indenting the code seems like it would be a rotten-but-salvageable compromise, > as it at least sets off the tags visually rather than making them appear as > though they are part of the code fragment. > > {code} > int foo = 1; > int bar = 2; > {code} > > Unfortunately, that's going to look like this in JIRA, because of a bug that > strips all leading whitespace from the first line. > > |-------------------------| > | int foo; | > | int bar; | > |-------------------------| > > It seems that this has been fixed by Atlassian in the Confluence wiki > (<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the > JIRA installation at issues.apache.org. So for now, I manually strip > indentation until the whole block is flush left. > > {code} > int foo = 1; > int bar = 2; > {code} > > (Gag. I vastly prefer wikis that automatically apply fixed-width styling to > any indented text.) > > One last tip for Lucy developers (and other non-Java devs). JIRA has limited > syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL > only -- and defaults to assuming your code is Java. In general, you want to > override that and tell JIRA to use "none". > > {code:none} > int foo = 1; > int bar = 2; > {code} > > Marvin Humphrey > > --------------------------------------------------------------------- To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org For additional commands, e-mail: java-dev-h...@lucene.apache.org
