Advertisement
Tag Archives: linking

Allura feature highlight – Artifact Linking

A very cool feature in the new SourceForge (Allura) that we haven’t touted enough is artifact linking. The ability to link to other parts of the forge is available in every Allura tool, providing tight integration between the various aspects of your project.

Any forge resource (“artifact”) can be linked with surrounding square brackets, e.g. [MyPage] or [#123]. These artifact links can take several forms.

Simple Links

Most commonly, the artifact identifier can simply be surrounded with square brackets. Here are some examples:


[MyWikiPage] # Wiki - name of wiki page
[#123] # Tracker - ticket number
[r10721] # SVN - revision number
[3b9d48] # Git & Mercurial - first 6 characters of revision hash
[2012/02/my-post] # Blog - post slug, including YYYY/MM/ prefix
[a6d38f98] # Discussion Thread - thread id
[a6d38f98#42f8] # Discussion Post - thread_id#post_id

Two-part Links

To link to an artifact in a specific tool, use the form: [tool:artifact], where tool is the name of the tool as it appears in the URL. Two-part links are useful when you have two tools of the same type installed. For example, let’s say you have a ‘bugs’ tracker and a ‘features’ tracker installed, and you want to link to the first ticket in each:


[bugs:#1]
[features:#1]

Put a tracker artifact link in a commit message to link that message to the ticket in the code browser.

Three-part Links

To link to an artifact in another project, use the form: [project:tool:artifact], where ‘project’ is the name of the project as it appears in the URL. For example:

[allura:wiki:Home]

To link to an artifact in a subproject, use the form: [project/subproject:tool:artifact], where ‘subproject’ is the name of the subproject as it appears in the URL. For example:

[allura/sub:code:3b9d48]

Back-links

Any time that you link to an artifact, that artifact will automatically link back. For example, if you link from ticket #2 to ticket #3, ticket #3 will automatically have a ‘Related’ section added to it, with a link back to ticket #2. Similarly, if you link to a ticket from a wiki page, that page will have a link back to the ticket.

Inline documentation

In any editing environment (ie, if you’re editing a blog post or a wiki page) you’ll see a “Formatting Help” button that will give you a pop-up help window with formatting instructions. That includes artifact linking, as well as all other aspects of formatting in Markdown.