Mailing-List: contact bloodhound-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: bloodhound-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of gary.martin@wandisco.com
 designates 74.125.82.178 as permitted sender)
Message-ID: <51250B28.9050500@wandisco.com>
Date: Wed, 20 Feb 2013 17:43:04 +0000
From: Gary Martin <gary.martin@wandisco.com>
User-Agent: Mozilla/5.0 (X11; Linux x86_64;
 rv:17.0) Gecko/20130106 Thunderbird/17.0.2
MIME-Version: 1.0
To: bloodhound-dev@incubator.apache.org
Subject: Re: [Apache Bloodhound] #390: Product wiki syntax
References: <055.88e62b912ed293164d9bc776d0fddb17@incubator.apache.org>
In-Reply-To: <055.88e62b912ed293164d9bc776d0fddb17@incubator.apache.org>
Content-Type: multipart/alternative;
 boundary="------------060004010804050201040601"

--------------060004010804050201040601
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

On 14/02/13 17:34, Apache Bloodhound wrote:
> #390: Product wiki syntax
> ---------------------+---------------
>    Reporter:  olemis  |    Owner:
>        Type:  task    |   Status:  new
>    Priority:  major   |  Version:
> Resolution:          |
> ---------------------+---------------
>   Add TracLinks for products and wiki syntax for product resources .
>

I am not sure that we have proper guidance for the product wiki syntax 
yet. I don't want to spend too long on this decision so here is a 
quickish overview of a few choices. My preference is stated at the end.

For consistency with the rest of the system we are almost certainly 
going to support product:prefix as a way of referring to a product as a 
whole. It would then seem reasonable to extend this to allow 
product:<prefix>:<resource> so for a prefix of bh we would have:

    product:bh -> link to the product
    product:bh:ticket:123 and product:bh:#123 -> links to ticket 123 in bh
    product:bh:milestone:m1 -> link to milestone m1 in bh

and so on. I would be happy to see this as a longhand form if this is 
seen as useful.

That syntax is a bit bulky and so I think we all expect some shorter 
form, particularly for tickets so we basically want an additional syntax 
of the form <prefix><sep><resource>. Some of the most obvious choices 
for the separator appear to be: '-', '/', '.' and ':'.

Before listing what these would look like for tickets, I would like to 
suggest that in the case of tickets, we could also drop the requirement 
to add a '#' to specify the ticket, this would force us to remove 
ambiguity for numeric wiki pages by requiring links like 
<prefix><sep>wiki:123, but I think that this is a small price to pay for 
brevity in ticket syntax. Therefore these appear to be the choices for 
representing #123 in product:bh in the shortest form:

    bh-123
    bh/123
    bh.123
    bh:123

and here is the same for milestone m1 in bh:

    bh-milestone:m1
    bh/milestone:m1
    bh.milestone:m1
    bh:milestone:m1

Each is likely to have their problems - the last case is interesting as 
it requires overloading InterTrac entries and could almost be emulated 
by users anyway if they prefer that form. There could also be clashes 
between defined InterTrac entries every so often though it might be 
possible to get around these problems. The first form matches the jira 
names for tickets but we may have to question if hyphens should be 
allowed in a prefix and whether we want to deal with that.

My preference is for '/' at this point - the only potential clash that 
springs to mind is with Wiki/Pages but those seem to require some 
specific uppercase rules. Are there any other problems others can spot?

Cheers,
     Gary

--------------060004010804050201040601--