Allow configuring prefix for referencing Issue and PRs

[davidsvantesson]

• Gitea version (or commit ref): 1.10.0

Description

Currently hash (#) is used to reference both PRs and issues. As issues and PRs uses the same number series per repository in Gitea this is not a problem. But if you use external issue tracker all references will refer to the external site, and it is not possible to refer a PR (except with the full url).

My suggestion is to allow configuring the prefix for references issues and PRs (independently) so it is possible to distinguish them. So in addition to the default (#) you can use e.g.

• another symbol ($, ¤, !).
• several letters like #PR123, #I123

Maybe anything can be allowed, but there should be some recommendation on suitable prefixes to not clash with other uses (e.g. '@' would be unsuitable).
The configuration could be made in app.ini (for site default) and per repo in settings.

Do you think this would be doable? Any comments?

[guillep2k]

I think it's doable, but I wouldn't make it freely configurable. I'd chose one alternate symbol set and let the user chose between them either for issues or PRs. ¤ is not available in all keyboards, but % should be.

[guillep2k]

Note: I'd have a three level setting in app.ini: no change, only for repositories with external trackers, or for all repositories. The no change setting is to maintain compatibility with existing repositories. I'd use the app.ini value as default for new reposotiries, and then the actual value should be stored in the repo itself. An UI to change it can be added in a later PR.

[davidsvantesson]

I think the hash sign is quite general accepted as reference for issues. The only thing I want to add is the ability to specify if reference to an issue or pr. So I am not sure there really is a need to change what symbol to use for referencing, or if a setting is needed...

Something I was positively surprised of was that Gitea already supports referring to issues in other organizations and repositories (in the format go-gitea/gitea#9088). Can we extend that to support specifying if the reference is to pr or issue? E.g. PR#9088 and ISSUE#9088 (preferably case insensitive so pr#9088 works as well). If you don't specify either it defaults to issue as today (redirected to pull if internal issue tracker is used). Possibly the default (pr or issue) can be a setting.

In combination with specifying repo it would be go-gitea/gitea/pr#9088 and go-gitea/gitea/issue#9088 (or is the reversed order better?)

[guillep2k]

I think the hash sign is quite general accepted as reference for issues. The only thing I want to add is the ability to specify if reference to an issue or pr. So I am not sure there really is a need to change what symbol to use for referencing, or if a setting is needed...

Something I was positively surprised of was that Gitea already supports referring to issues in other organizations and repositories (in the format go-gitea/gitea#9088). Can we extend that to support specifying if the reference is to pr or issue? E.g. PR#9088 and ISSUE#9088 (preferably case insensitive so pr#9088 works as well). If you don't specify either it defaults to issue as today (redirected to pull if internal issue tracker is used). Possibly the default (pr or issue) can be a setting.

In combination with specifying repo it would be go-gitea/gitea/pr#9088 and go-gitea/gitea/issue#9088 (or is the reversed order better?)

You're right, currently there's no way of referencing a PR in the same repo. But you've also made me just realize that the cross-repo references are completely broken when they are in or refer to a repo with external issue tracker because the repo.metas() are always taken from the repository of the rendered content. 😢

Anyway, we can allow PR# for repos with external issue trackers, but that will be a problem for cross references too. Oh, it's very complicated!

[guillep2k]

I'm trying to complete this table, can you help me?

Reference in User1/Repo1	Repo1 issues are external	RepoZ issues are external	Should render
#1234	no	N/A	A link to issue/pull 1234 in User1/Repo1
User1/Repo1#1234	no	N/A	A link to issue/pull 1234 in User1/Repo1
UserZ/RepoZ#1234	N/A	no	A link to issue/pull 1234 in UserZ/RepoZ
#1234	yes	N/A	A link to external issue 1234 for User1/Repo1
User1/Repo1#1234	yes	N/A	A link to external issue 1234 for User1/Repo1
UserZ/RepoZ#1234	N/A	no	A link to issue/pull 1234 in UserZ/RepoZ
UserZ/RepoZ#1234	N/A	yes	A link to external issue 1234 for UserZ/RepoZ
PR#1234	N/A	N/A	A link to PR 1234 in User1/Repo1
User1/Repo1 ???	N/A	N/A	A link to PR 1234 in User1/Repo1
UserZ/RepoZ ???	N/A	N/A	A link to PR 1234 in UserZ/RepoZ
-	-	-	-
AAA-1234	yes	N/A	A link to external issue AAA-1234 for User1/Repo1
User1/Repo1 ??? AAA-1234	yes	N/A	A link to external issue AAA-1234 for User1/Repo1
UserZ/RepoZ ??? AAA-1234	N/A	yes	A link to external issue AAA-1234 for UserZ/RepoZ

The latest section if for issues with alphanumeric format (I guess some external tracker uses that).

[davidsvantesson]

I just looked in a bit on alphanumeric a bit and I don't think they work as you specified, they seem to be without hash (see regex).

You have typo on row 6 (wrong repo)

[guillep2k]

I just looked in a bit on alphanumeric a bit and I don't think they work as you specified, they seem to be without hash (see regex).

You're right. I forgot. I wrote that myself. 😋

[davidsvantesson]

I think we should have

• User1/Repo1/PR#1234
• UserZ/RepoZ/PR#1234

Also I think it would be neat to support this:

• RepoX#1234
• RepoX/PR#1234
  (org default to the same as repo that reference is made from).

But maybe that is problematic if someone fork the repo.... ?

[guillep2k]

But maybe that is problematic if someone fork the repo.... ?

I don't think forks are problematic as they don't migrate issues/PRs.

RepoX/#1234 and User1/Repo1/PR#1234 do not conform to the currently supported syntax (which we must continue to support). Somehow seems a little hacky? User1/Repo1#PR1234 sounds like a better fit to me, but I just saw another user use the PR#1234 syntax in a PR on this very repo, which makes me think that other systems use it (GitHub ignored it, by the way).

The thing is that too many options will become a burden, because it limits what you can write without creating a reference (you cannot choose if the reference is created or not). References will be seen in the referenced issue/PR as a comment and can't be deleted (they will be formatted with strike through if removed).

[davidsvantesson]

I don't understand why it doesn't conform to current syntax, it would still support both User1/Repo1#1234 and User1/Repo1/PR#1234. So I don't see a problem with backwards compatibility. This change shouldn't force specifying if the link is to issue or pr, the default would still be issues (possibly configurable).

Regarding RepoX/#1234 it would be the same. Only if someone have written RepoX/#1234 somewhere today and don't expect it to render a reference it would break the backwards compatibility. The problem with forks can be that after forking the repo is not in OrgX any longer but under UserY, so the cross reference would change to try to find the same repo under UserY (which doesn't have the issue).

At least I think the style should be the same for internal and cross-references, so either

• PR#1234 and org/repo/PR#1234, OR
• #PR1234 and org/repo#PR1234

[guillep2k]

I don't understand why it doesn't conform to current syntax, it would still support both User1/Repo1/#1234 and User1/Repo1/PR#1234.

You've got an extra /. It's: User1/Repo1#1234, not User1/Repo1/#1234.

[davidsvantesson]

Sorry, that shouldn't be there. Only if you want to specify it's an PR reference you need the extra slash, so User1/Repo1#1234 is the normal syntax and User1/Repo1/PR#1234 to specify it's a PR reference.

[guillep2k]

Sorry, that shouldn't be there. Only if you want to specify it's an PR reference you need the extra slash, so User1/Repo1#1234 is the normal syntax and User1/Repo1/PR#1234 to specify it's a PR reference.

That's what I find hacky. But perhaps it's the best we can do. How do you feel about #PR1234? It shouldn't clash with anything.

[davidsvantesson]

I prefer having it before, partly because #PR1234 looks like another issue numbering system (quite similar to the alphanumeric). But I think it is mostly a question of taste.

Maybe the alphanumeric style should be left out from this, at last for now? It would limit that you can't refer to an alphanumeric issue on another repo, but you can still refer to both PRs and numeric issues. I'm afraid it would add to many clashes with normal written text.