Difference between revisions of "Template:Single-page JS tracker"

From Free Software Directory
Jump to: navigation, search
m (Separate single-page issue tracker.)
(Move documentation to main page, as a fix for issue #8.)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
<noinclude>This should only be used at [[FSD:Single-page JS tracker]].</noinclude><includeonly><div id="{{BacklogIssue/HTMLid|id={{{id|}}}}}" class="backlogIssue {{{extraClasses|}}}" data-id="{{{id|0}}}" data-extraclasses="{{{extraClasses|}}}" {{BacklogIssue/stalledBy|deps={{{stalledBy|}}}}}>
+
<noinclude>This should only be used at [[FSD:Single-page JS tracker]].
−
  <div class="backlogIssueAnchor">{{#if:{{{id|}}}|{{BacklogIssue/HTMLid|id={{{id}}}}}|ERROR: <nowiki>"|id="</nowiki> parameter missing!}}</div>
+
 
 +
== Instructions ==
 +
 
 +
All Tasks/Issues inside the Backlog must use this template.<br>Reading and understanding this document requires less than 10 minutes.
 +
 
 +
<small>Note: the token <code>Template:</code> is optional.</small>
 +
 
 +
<small>Note: ensure JavaScript is enabled/unblocked in your web browser.</small>
 +
 
 +
=== Create a new Task/Issue ===
 +
 
 +
To create a new Task with id <code>34gcsdr</code> and content <code>issue text</code>, write the following wikitext:
 +
 
 +
<code><nowiki>{{Template:Single-page JS tracker|id=34gcsdr|text=issue text}}</nowiki></code>
 +
 
 +
* 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 <code>id</code> will be automatically replaced with a dash and the entire <code>id</code> it will automatically processed to become a valid title.<br>
 +
The Preview function of the [[Free_Software_Directory:Backlog_active|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.
 +
 
 +
<small>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.</small>
 +
 
 +
==== Examples of Task generation ====
 +
 
 +
1. Example: <code><nowiki>{{Single-page JS tracker|id=page A shows error XYZ|text= &hellip; }}</nowiki></code>
 +
* ...its ID is converted to: <code>id=page-A-shows-error-XYZ</code>;
 +
* ...is listed as: <code>Page a shows error XYZ;</code>;
 +
* ...is different from: <code><nowiki>{{Single-page JS tracker|id=Page a shows error XyZ|text= &hellip; }}</nowiki></code>;
 +
* ...produces the link: <code>https://directory.fsf.org/wiki/Free_Software_Directory:Backlog_active#page-A-shows-error-XYZ</code>.
 +
 
 +
2. Example: <code><nowiki>{{Single-page JS tracker|id=page-A-shows-error-XYZ|text= &hellip; }}</nowiki></code>
 +
* ...its ID is not converted (already valid);
 +
* ...is listed with the same name of Example 1;
 +
* ...is different from: <code><nowiki>{{Single-page JS tracker|id=page-A_shows_error-XYz|text= &hellip; }}</nowiki></code>
 +
* ...produces the same link of Example 1.
 +
 
 +
The content of the <code>text</code> 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 <code>34gcsdr</code> from any document (wikipages, emails, IRC and so on) write the following URL:
 +
 
 +
* Active backlog: <code>https://directory.fsf.org/wiki/Free_Software_Directory:Backlog_active#34gcsdr</code>
 +
* Backlog archive: <code>https://directory.fsf.org/wiki/Free_Software_Directory:Backlog_archive#34gcsdr</code>
 +
 
 +
<small>(replace the id with the id of your own Task/Issue)</small>
 +
 
 +
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.
 +
 
 +
<small>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.</small>
 +
 
 +
==== Task/Issue local referencing ====
 +
 
 +
You can use the [https://www.mediawiki.org/wiki/Help:Links#Internal_links anchor syntax] of MediaWiki to reference a Task/Issue from another Task/Issue on the same page:
 +
 
 +
===== Examples of local referencing =====
 +
 
 +
* <code><nowiki>{{Template:Single-page JS tracker|id=another issue|text= &hellip; and local reference to the issue [[#34gcsdr]] which should be solved in 2 weeks.}}</nowiki></code>
 +
* <code><nowiki>{{Template:Single-page JS tracker|id=another issue|text=local reference to [[#34gcsdr|issue 34gcsdr]] and &hellip; }}</nowiki></code>
 +
 
 +
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 [https://www.mediawiki.org/wiki/Help:Links#Internal_links 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 =====
 +
 
 +
* <code><nowiki>Please read the issue [[Free_Software_Directory:Backlog_active#34gcsdr]], which should be solved in 2 weeks.</nowiki></code>
 +
* <code><nowiki>Please read the [[Free_Software_Directory:Backlog_active#34gcsdr|issue 34gcsdr]] and let me know your opinion.</nowiki></code>
 +
* <code><nowiki>We've finally solved [[Free_Software_Directory:Backlog_archive#34gcsdr|issue 34gcsdr]] and we are proud of the final result!</nowiki></code>
 +
 
 +
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:
 +
 
 +
* <code><nowiki>{{Template:Single-page JS tracker|id=new issue|text=this issue is similar to the old [[Free_Software_Directory:Backlog_archive#34gcsdr|issue 34gcsdr]] we solved last week and &hellip; }}</nowiki></code>
 +
 
 +
=== Prioritize a Task/Issue ===
 +
 
 +
In addition than using wordings like "TOP PRIORITY" in the <code>id</code> 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:
 +
 
 +
<code><nowiki>{{Template:Single-page JS tracker/TopPriorityBacklogIssue| &hellip; }}</nowiki></code>
 +
 
 +
* &hellip; -- the same parameters of <code>Template:Single-page JS tracker</code>
 +
 
 +
...will create a <span style="color:gold;background-color:black;padding:0.2em;font-size:small;">TOP PRIORITY</span> task, which will be categorized and stylized as such.
 +
 
 +
Members of the [[Free_Software_Directory:Backlog_Admin_Group|BAG]] might give priority to <span style="color:gold;background-color:black;padding:0.2em;font-size:small;">TOP PRIORITY</span> tasks.<br>
 +
<span style="color:gold;background-color:black;padding:0.2em;font-size:small;">TOP PRIORITY</span> 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 <i>only</i> if the page contains at least one <code>Single-page JS tracker/TopPriorityBacklogIssue</code> 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 <code>id</code>), 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 <code>id</code>s separated by any delimiter amongst <code>;</code>, <code>,</code> and space:
 +
 
 +
<code><nowiki>{{Template:Single-page JS tracker|id=34gcsdr|stalledBy=#issue-A-1, #page-A_shows_error-XYz, &hellip;| &hellip; }}</nowiki></code>
 +
 
 +
<code><nowiki>{{Template:Single-page JS tracker/TopPriorityBacklogIssue|id=34gcsdr|stalledBy=#page-A_shows_error-XYz, #issue-B-3, &hellip;| &hellip; }}</nowiki></code>
 +
 
 +
...this will generate a [https://www.json.org/json-en.html JSON] list of <code>id</code>s at the bottom of the Task/Issue and inside of the special <code>data-stalledby</code> HTML attribute, ensuring both readability by humans and parsability by bots and/or scripts.
 +
 
 +
<small>Tip: you can add non-existent ids and create them later, as all scripts/bots must be fault-tolerant.<br></small>
 +
<small>Tip: the list will never be sorted automatically, so feel free to use an arbitrary order from left to right.</small>
 +
 
 +
Members of the [[Free_Software_Directory:Backlog_Admin_Group|BAG]] can save precious time by solving the elements referred by this list before the current Task/Issue.<br>
 +
Instead of writing the dependencies in the <code>text</code> parameter, it is definitely a good idea to use this feature extensively. --[[User:LorenzoAncora|LorenzoAncora]] ([[User talk:LorenzoAncora|talk]])
 +
</noinclude><includeonly><div id="{{Single-page JS tracker/HTMLid|id={{{id|}}}}}" class="backlogIssue {{{extraClasses|}}}" data-id="{{{id|0}}}" data-extraclasses="{{{extraClasses|}}}" {{Single-page JS tracker/stalledBy|deps={{{stalledBy|}}}}}>
 +
  <div class="backlogIssueAnchor">{{#if:{{{id|}}}|{{Single-page JS tracker/HTMLid|id={{{id}}}}}|ERROR: <nowiki>"|id="</nowiki> parameter missing!}}</div>
 
  <div class="backlogIssueContent">{{{text|ERROR: <nowiki>"|text="</nowiki> parameter missing!}}}</div>
 
  <div class="backlogIssueContent">{{{text|ERROR: <nowiki>"|text="</nowiki> parameter missing!}}}</div>
 
</div>
 
</div>
−
{{#subobject:BacklogIssue-{{BacklogIssue/HTMLid|id={{{id|}}}}}
+
{{#subobject:BacklogIssue-{{Single-page JS tracker/HTMLid|id={{{id|}}}}}
 
|id={{{id|0}}}
 
|id={{{id|0}}}
 
|extraClasses={{{extraClasses|}}}
 
|extraClasses={{{extraClasses|}}}
 
|stalledBy={{{stalledBy|}}}
 
|stalledBy={{{stalledBy|}}}
 
}}<includeonly>
 
}}<includeonly>

Latest revision as of 15:11, 8 October 2021

This should only be used at FSD:Single-page JS tracker.

Instructions

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:Single-page JS tracker|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: {{Single-page JS tracker|id=page A shows error XYZ|text= … }}

2. Example: {{Single-page JS tracker|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: {{Single-page JS tracker|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:Single-page JS tracker|id=another issue|text= … and local reference to the issue [[#34gcsdr]] which should be solved in 2 weeks.}}
  • {{Template:Single-page JS tracker|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:Single-page JS tracker|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:Single-page JS tracker/TopPriorityBacklogIssue| … }}

  • … -- the same parameters of Template:Single-page JS tracker

...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 Single-page JS tracker/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:Single-page JS tracker|id=34gcsdr|stalledBy=#issue-A-1, #page-A_shows_error-XYz, …| … }}

{{Template:Single-page JS tracker/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.

Retrieved from "https://directory.fsf.org/wiki?title=Template:Single-page_JS_tracker&oldid=85977"