You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@bloodhound.apache.org by Gary Martin <ga...@wandisco.com> on 2013/02/20 18:43:04 UTC
Re: [Apache Bloodhound] #390: Product wiki syntax
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
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Olemis Lang <ol...@gmail.com>.
On 3/5/13, Gary Martin <ga...@wandisco.com> wrote:
> On 04/03/13 22:39, Olemis Lang wrote:
>> even if we don't choose sep = '-' it seems it may be matched
>>
>> so far I have discarded these chars as prefixes
>>
>> / collisions with relative wiki page refs in wiki context
>> - has a major ambiguity when it comes to expanding raw-attachment and
>> similar TracLinks namespace
>> : TracLinks meta-char , obviously out
>> . collisions with relative wiki
>>
>> I'm starting to think that we should be using one of ~ >
>>
>> 1. prefix~#123
>> 2. prefix>#123
>>
>> ... or a combination of the former e.g.
>>
>> 3. prefix->#123
>>
>> I think I'd rather prefer 1 or 3 . In the first version I'll implement
>> (1)
>
> Well, I have considered those and I might compromise (I prefer '>') but...
>
ok . I'll use that . No problem .
;)
> The case of raw-attachment is a very good point. However, it is possible
> to get around it and it also has a particular major advantage if we ever
> get people to defect from jira. In order to achieve that I would be
> prepared to drop the requirement to be able to use the short form for
> anything other but tickets. In particular PREFIX-123 would be the
> important case.
>
+1
> If we are interested in more, it would be possible to get away with '-'
> under more conditions by specifying only uppercase namespaces are
> allowed or making by deciding how a clash with other link resolvers will
> be resolved. It should be noted that '-' is a problem for
> 'raw-attachment' because of 'attachment'.
>
> It might be annoying for the raw product that you are unable to refer to
> attachments in that form but from within the product I still expect
> users to be able to drop the prefix and externally there is still the
> product:raw:attachment: form.
>
The fact is that external link resolvers (i.e. wiki syntax extensions)
will be matched first , so afaict the result of making both work
side-by-side will be the impossibility of using raw-attachment prefix
at all , i.e. no fallback possible
--
Regards,
Olemis.
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Gary Martin <ga...@wandisco.com>.
On 04/03/13 22:39, Olemis Lang wrote:
> even if we don't choose sep = '-' it seems it may be matched
>
> so far I have discarded these chars as prefixes
>
> / collisions with relative wiki page refs in wiki context
> - has a major ambiguity when it comes to expanding raw-attachment and
> similar TracLinks namespace
> : TracLinks meta-char , obviously out
> . collisions with relative wiki
>
> I'm starting to think that we should be using one of ~ >
>
> 1. prefix~#123
> 2. prefix>#123
>
> ... or a combination of the former e.g.
>
> 3. prefix->#123
>
> I think I'd rather prefer 1 or 3 . In the first version I'll implement (1)
Well, I have considered those and I might compromise (I prefer '>') but...
The case of raw-attachment is a very good point. However, it is possible
to get around it and it also has a particular major advantage if we ever
get people to defect from jira. In order to achieve that I would be
prepared to drop the requirement to be able to use the short form for
anything other but tickets. In particular PREFIX-123 would be the
important case.
If we are interested in more, it would be possible to get away with '-'
under more conditions by specifying only uppercase namespaces are
allowed or making by deciding how a clash with other link resolvers will
be resolved. It should be noted that '-' is a problem for
'raw-attachment' because of 'attachment'.
It might be annoying for the raw product that you are unable to refer to
attachments in that form but from within the product I still expect
users to be able to drop the prefix and externally there is still the
product:raw:attachment: form.
Cheers,
Gary
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Olemis Lang <ol...@gmail.com>.
I have been tempted to write a long reply , but I won't . I'll just
reply quicly between the lines . Product wiki syntax is almost ready
and working . I'm just writing test cases to cover all forms and deal
with some exotic . I propose we focus our efforts on discussing about
how to improve what I'll submit in the next few days , once we all be
aware of the limitations and technical challenges solved and pending
;)
BTW , After getting my hands dirty I realized that *many* of the
previous suggestions mentioned before are not even valid TracLinks
expressions . That will shape the form of the final solution though .
On 3/4/13, Gary Martin <ga...@wandisco.com> wrote:
> On 21/02/13 10:14, Andrej Golcov wrote:
>> Regarding prefixing tickets with "#".
>> We still have to support #123 notation for wiki links inside the
>> product. IMHO, introducing non-relative wiki links for tickets without
>> # (e.g. bh/123) can be user confusing. My +1 to leave # for full
>> path tickt links, e.g. #produc<delimeter>productid
>>
>> Regards, Andrej
>
> In case it isn't spotted from another related thread, I believe that
> when using # in the link, it should always appear after any product
> specification.
+1
> The forms for the links will therefore be
>
> * <reslink>
> * product:<prefix>:<reslink>
> * <prefix><sep><reslink>
>
+1
> where <reslink> is any currently valid resource link (#<id>,
> ticket:<id>, milestone:<id>, wiki:<id> etc).
+1 ... though ... ;)
> In addition, specifically
> for tickets and wiki pages we will allow:
>
> * <prefix><sep><id>
>
for tickets +1 . for wiki pages I'm not sure
> as long as the wiki page matches the current rules for automatically
> being interpreted as wikipage links. On this basis we will be able to
> match the the form of jira tickets if we choose <sep> = '-'
even if we don't choose sep = '-' it seems it may be matched
so far I have discarded these chars as prefixes
/ collisions with relative wiki page refs in wiki context
- has a major ambiguity when it comes to expanding raw-attachment and
similar TracLinks namespace
: TracLinks meta-char , obviously out
. collisions with relative wiki
I'm starting to think that we should be using one of ~ >
1. prefix~#123
2. prefix>#123
... or a combination of the former e.g.
3. prefix->#123
I think I'd rather prefer 1 or 3 . In the first version I'll implement (1)
> and maybe we
> should just do so. Some of the things to consider for that are:
>
> * false matches on 'var-N' which would either have to be escaped by
> one of the standard means or just written as 'var - N'
+1
> * potential ambiguity if '-' is allowed in the prefix itself,
in any case only alphanumeric (inlcuding unicode) chars will be
supported in short forms .
> which
> might suggest we should avoid the issue by disallowing products
> being set up with '-' in the prefix; existing products with this
> will work with 'product:<prefix>:<reslink>' syntax of course.
>
Other kinds of prefixes will make use of link resolvers only .
> Does anyone spot any additional problems or have any objections to this?
>
let the test suite talk , please be patient
;)
--
Regards,
Olemis.
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Gary Martin <ga...@wandisco.com>.
On 21/02/13 10:14, Andrej Golcov wrote:
> Regarding prefixing tickets with "#".
> We still have to support #123 notation for wiki links inside the
> product. IMHO, introducing non-relative wiki links for tickets without
> # (e.g. bh/123) can be user confusing. My +1 to leave # for full
> path tickt links, e.g. #produc<delimeter>productid
>
> Regards, Andrej
In case it isn't spotted from another related thread, I believe that
when using # in the link, it should always appear after any product
specification. The forms for the links will therefore be
* <reslink>
* product:<prefix>:<reslink>
* <prefix><sep><reslink>
where <reslink> is any currently valid resource link (#<id>,
ticket:<id>, milestone:<id>, wiki:<id> etc). In addition, specifically
for tickets and wiki pages we will allow:
* <prefix><sep><id>
as long as the wiki page matches the current rules for automatically
being interpreted as wikipage links. On this basis we will be able to
match the the form of jira tickets if we choose <sep> = '-' and maybe we
should just do so. Some of the things to consider for that are:
* false matches on 'var-N' which would either have to be escaped by
one of the standard means or just written as 'var - N'
* potential ambiguity if '-' is allowed in the prefix itself, which
might suggest we should avoid the issue by disallowing products
being set up with '-' in the prefix; existing products with this
will work with 'product:<prefix>:<reslink>' syntax of course.
Does anyone spot any additional problems or have any objections to this?
Cheers
Gary
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Andrej Golcov <an...@digiverse.si>.
Regarding prefixing tickets with "#".
We still have to support #123 notation for wiki links inside the
product. IMHO, introducing non-relative wiki links for tickets without
# (e.g. bh/123) can be user confusing. My +1 to leave # for full
path tickt links, e.g. #produc<delimeter>productid
Regards, Andrej
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Gary Martin <ga...@wandisco.com>.
On 20/02/13 18:41, Olemis Lang wrote:
> On 2/20/13, Olemis Lang <ol...@gmail.com> wrote:
>> On 2/20/13, Gary Martin <ga...@wandisco.com> wrote:
>>> On 14/02/13 17:34, Apache Bloodhound wrote:
>>>> #390: Product wiki syntax
> [...]
>>> 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?
>>>
>> AFAICR bh/whateever within a wiki page context will be expanded to
>> relative page . I guess hyphens and/or dots are less problematic
>> (unless I'm missing something ;) .
>>
> jftr ... I'm mainly saying that this will be problematic with the long
> form e.g. [bh/milestone:m1 caption]
>
As far as I can tell, that will not be a problem. The only problem will
be for wiki pages when someone specifies in these forms:
Bh/WikiPage
Bh/Wikipage
both of which are currently already treated as wikipages. The first we
would want to be interpreted as a link to WikiPage in the Bh product.
Perhaps it is a little much to say that we only accept all uppercase or
all lowercase as the prefix.
Cheers,
Gary
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Olemis Lang <ol...@gmail.com>.
On 2/20/13, Olemis Lang <ol...@gmail.com> wrote:
> On 2/20/13, Gary Martin <ga...@wandisco.com> wrote:
>> On 14/02/13 17:34, Apache Bloodhound wrote:
>>> #390: Product wiki syntax
[...]
>>
>> 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?
>>
>
> AFAICR bh/whateever within a wiki page context will be expanded to
> relative page . I guess hyphens and/or dots are less problematic
> (unless I'm missing something ;) .
>
jftr ... I'm mainly saying that this will be problematic with the long
form e.g. [bh/milestone:m1 caption]
--
Regards,
Olemis.
Re: [Apache Bloodhound] #390: Product wiki syntax
Posted by Olemis Lang <ol...@gmail.com>.
On 2/20/13, Gary Martin <ga...@wandisco.com> wrote:
> 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 .
>>
>
[...]
>
> 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
>
+1
This is consistent with my initial idea . I just didn't want to spend
time writing this and prioritize #355 i.e. TC conversion
> and so on. I would be happy to see this as a longhand form if this is
> seen as useful.
>
its a MUST as a last recourse for disambiguation .
[...]
> 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.
IMO there's no need to drop it ... we can add numeric patterns rules
to consider them as ticket IDs by default .
> 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.
-1 for : separator char
> 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?
>
AFAICR bh/whateever within a wiki page context will be expanded to
relative page . I guess hyphens and/or dots are less problematic
(unless I'm missing something ;) .
--
Regards,
Olemis.