Template talk:BacklogIssue

From Free Software Directory
Jump to: navigation, search


All Tasks/Issues inside the Backlog must use this template.
Reading and understanding this document requires less than 10 minutes.

Note: the token Template: is optional.

Note: ensure JavaScript is enabled/unblocked in your web browser.

Create a new Task/Issue

To create a new Task with id 34gcsdr and content issue text, write the following wikitext:

{{Template:BacklogIssue|id=34gcsdr|text=issue text}}

  • id=0:string -- arbitrary unique case-sensitive string. It should summarize the Issue/Task and is also used to generate an HTML anchor;
  • text:string -- text of the backlog issue. Supports both multiline wikitext and HTML.

All spaces inside id will be automatically replaced with a dash and the entire id it will automatically processed to become a valid title.
The Preview function of the Development Plan shows its appearance both in the Advanced ToC widget (the drop-down navigation menu) and in the page itself, so what you see is what you get.

Tip: when previewing the page, you can use the search function of your web browser to ensure the ID shown in the preview is unique.

Examples of Task generation

1. Example: {{BacklogIssue|id=page A shows error XYZ|text= … }}

2. Example: {{BacklogIssue|id=page-A-shows-error-XYZ|text= … }}

  • ...its ID is not converted (already valid);
  • ...is listed with the same name of Example 1;
  • ...is different from: {{BacklogIssue|id=page-A_shows_error-XYz|text= … }}
  • ...produces the same link of Example 1.

The content of the text parameter (intentionally shortened in this document) is multi-line and supports both HTML markup and WikiCode and the result is spaced from the rest of the page, so you can create Issues/Tasks of arbitrary length and complexity without compromising the appearance of the edits by other collaborators.

Recall a Task/Issue

To recall the example Task/Issue with id 34gcsdr from any document (wikipages, emails, IRC and so on) write the following URL:

(replace the id with the id of your own Task/Issue)

If the Task exists, end user's browser will scroll automatically to reach it once the page is fully loaded. If two Issues/Tasks collide (have exactly the same ID), the one higher in the page always prevail.

Tip: you can also obtain the URL of a Task/Issue by selecting its name from the Advanced ToC widget and then copying the text inside the navigation bar of your browser. URLs obtained this way are guaranteed to be correct.

Task/Issue local referencing

You can use the anchor syntax of MediaWiki to reference a Task/Issue from another Task/Issue on the same page:

Examples of local referencing
  • {{Template:BacklogIssue|id=another issue|text= … and local reference to the issue [[#34gcsdr]] which should be solved in 2 weeks.}}
  • {{Template:BacklogIssue|id=another issue|text=local reference to [[#34gcsdr|issue 34gcsdr]] and … }}

This effectively eliminates the need to use complete URLs to reference two or more issues inside the same page of the Backlog.

Task/Issue cross-page referencing

You can use the remote anchor syntax of MediaWiki to reference a Task/Issue from another Task/Issue on different pages of this wiki:

Examples of cross-page referencing
  • Please read the issue [[Free_Software_Directory:Backlog_active#34gcsdr]], which should be solved in 2 weeks.
  • Please read the [[Free_Software_Directory:Backlog_active#34gcsdr|issue 34gcsdr]] and let me know your opinion.
  • We've finally solved [[Free_Software_Directory:Backlog_archive#34gcsdr|issue 34gcsdr]] and we are proud of the final result!

This effectively eliminates the need to use complete URLs to reference two or more issues inside different pages of the Backlog and both in Talk and Discussion pages.

When referencing an archived (resolved) issue from an unresolved issue, you can create a link towards it using the same syntax:

  • {{Template:BacklogIssue|id=new issue|text=this issue is similar to the old [[Free_Software_Directory:Backlog_archive#34gcsdr|issue 34gcsdr]] we solved last week and … }}

Prioritize a Task/Issue

In addition than using wordings like "TOP PRIORITY" in the id parameter, it is possible to enable the system to see a new or an existing Issue/Task as Top Priority by using the following syntax:

{{Template:TopPriorityBacklogIssue| … }}

  • … -- the same parameters of Template:BacklogIssue

...will create a TOP PRIORITY task, which will be categorized and stylized as such.

Members of the BAG might give priority to TOP PRIORITY tasks.
TOP PRIORITY Tasks are always shown before other tasks in the Advanced ToC widget of the Backlog pages.

The Top Priority filter

The Advanced ToC widget of the Backlog pages has an helper, called Top Priority filter. It has the shape of a little grey star and appears on the right side of the Advanced ToC only if the page contains at least one TopPriorityBacklogIssue template.

Clicking on the star emoji (⭐) will immediately hide all standard Issues/Tasks, leaving only the prioritized ones; the effect can be reversed by clicking again when the star is enlightened. When the filter is active the Advanced ToC widget loses part of its functionality as jumping to hidden Issues/Tasks is impossible (however, you can still get their id), so the filter is automatically deactivated when its container page is reloaded.

Task/Issue dependencies

Issues can be organized hierarchically through the concept of stall: a Task/Issue is in stall when it depends on the resolution of other entries before it can be resolved itself.

This template offers the special "stalledBy" parameter, which accepts a list of ids separated by any delimiter amongst ;, , and space:

{{Template:BacklogIssue|id=34gcsdr|stalledBy=#issue-A-1, #page-A_shows_error-XYz, …| … }}

{{Template:TopPriorityBacklogIssue|id=34gcsdr|stalledBy=#page-A_shows_error-XYz, #issue-B-3, …| … }}

...this will generate a JSON list of ids at the bottom of the Task/Issue and inside of the special data-stalledby HTML attribute, ensuring both readability by humans and parsability by bots and/or scripts.

Tip: you can add non-existent ids and create them later, as all scripts/bots must be fault-tolerant.
Tip: the list will never be sorted automatically, so feel free to use an arbitrary order from left to right.

Members of the BAG can save precious time by solving the elements referred by this list before the current Task/Issue.
Instead of writing the dependencies in the text parameter, it is definitely a good idea to use this feature extensively. --LorenzoAncora (talk)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the page “GNU Free Documentation License”.

The copyright and license notices on this page only apply to the text on this page. Any software or copyright-licenses or other similar notices described in this text has its own copyright notice and license, which can usually be found in the distribution or license text itself.