lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simon Willnauer <simon.willna...@googlemail.com>
Subject Re: Composing posts for both JIRA and email (was a JIRA post)
Date Thu, 04 Mar 2010 17:49:43 GMT
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 <marvin@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-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org


Mime
View raw message