Semantic MediaWiki: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
{{wiki-gang}}
{{TOCright}}

There's a lot of information on {{SERVERNAME}}.
[[wikipedia:Semantic MediaWiki]] is an extension that lets you annotate existing wiki text and templates so that you can query and explore this information.
Done right we get less duplication, more standardization, and easy information reuse.

[[mw:Semantic Forms]] is another extension that exploits SMW to let users edit template information in a form.

== Where Semantics are being used ==
You can browse [[Special:Properties]] to see properties in use.
You can use [[Special:Allpages]] to display Form: pages.

=== For tests ===
Many tests are using semantic annotations, so we can query for them. See [[Test cases 8.2.0]] and [[Testcase Query Examples]].

To display query results so that they look like the test case (green badge), use <tt>format=embedded</tt>. To display in some other format, someone has to create Template:Display_query_row_in_a_gray_box and use <tt>format=template | template=Display query row in a gray box</tt>

Some test results are also using semantic annotations, see [[TestResults 8.2.0]].

==== Issues for Test cases ====
* Compare [[Tests/Sugar Control Panel/About Me/Color Change]] and Eben's [[Tests/Home view]], latter uses different terminology: Justification ''(like Feature?)'', Actions ''(like Procedure?'', Verify ''(like Expected results and pass criteria?''
* [[Property:Build stream]] could usefully have service links to builds, diffs, packages, etc. This requires lowercase names (most URL's use <tt>joyride</tt>, not ''Joyride''). See [[Property:Build stream]] for a discussion.

===== Structuring Test cases =====
We are using long titles that identify area, e.g. [[Tests/Sugar_Control_Panel/About_Me/Color_Change]].
Putting the organization in the name ensures test cases will appear in a useful order in generic queries.

Could also/instead use subcategories of [[:Category:Test cases]] to identify the kind of test, but Semantic Forms has limited capability to assign categories. A query for a category will find things in its subcategories, so it's fine to have a detailed category hierarchy.

It might be possible to query for test cases "like" Tests/Sugar_*. to only show certain test cases.

==== Issues for test results ====
The form editor lets you add multiple test results to a test case.
So a page like [[Tests/Upgrades/DataIntegrity]] can have ''both'' values for [[Property:PassFail]], and you can't tell in a query which one is associated with a particular build.
To isolate each result, you would have to create a separate page for each combination of test case and build, e.g. ''TR_Build2230/Upgrades/DataIntegrity''. That's a lot of pages to name, although [http://www.mediawiki.org/wiki/Extension:Semantic_Forms#The_one-step_process Semantic Forms can automatically generate a unique page as you fill in a form]]. Is there any reason to have semantics for each test result, when you can simply visit a page with the test results?

Details: [[Form:Test_case]] somehow has adds a [[Template:Test results]] for each test result. There's also [[Form:Test Results]] which brings up a broken editing form and invokes a non-existent [[Template:Test Results]], see [[Try_to_break_2]].

* TODO: figure out a generic way to have a link _Log a test result_ that when clicked goes to [[Form:Test_result]] and the wiki editor fills in a form that creates a test result linked to the original page. Then any page with a test on it can be "filled out" with test results that anyone can enter!
** Try it:
*** [[Special:AddPage/Test_Results/Trying_to_break]]
*** {{#formlink:Test_Results|add a result for "Trying to break"|query_string}}

* [[Property:PassFail]] perhaps should be Type:boolean, just Pass true/false.
* [[Property:Trac bug number]] perhaps should be Type:URL, see discussion above.

=== For projects and tasks===
see [[Form:Tasks]] and [[Form:Project]], and their respective template pages [[Template:Task]] and [[Template:Project]]. We would like to use the Project, and Task forms to track projects, and to some extent replace the project database. The tasks template should be for small open tasks that will then be populated on aggregate pages based on various properties like priority and skill set required.

=== For deployments ===

All deployments have the [[Template:Deployment|deployment template]] on them. They also have the "edit with form" tab on the main page. This is seen on for example [[OLPC Peru]]. This information is aggregated on the page [[Deployments]], using a semantic query. Also see [[Deployment query examples]].

=== For activities ===

There is currently the [[Template:Activity page]] that is annotates general information about activities. [[Form:Activity]] fills this in. There is also a [[Template:Activity bundle]] that allows for multiple bundle versions so that you can keep track of, for example, the last activity version that works with build 656 separately from the latest version.
: The '''To add another activity version that works with other builds click "add another''' form interface works nicely for editing, but ''doesn't work'' for querying! It just adds more [[Property:Activity version]] and [[Property:Activity bundle]] values to the page &mdash; they ''aren't grouped together in any way except visually''. This is the same underlying issue as adding multiple Test results to a test case, see [[#Issues for test results]]. -- [[User:Skierpage|Skierpage]] 01:08, 14 September 2008 (UTC)

We need to fix the templates so they can tell the difference betweeen latest version and the versions that work on earlier releases.

There are queries of this in:
* [[9.1.0#Lists of candidate activities]] has various lists of activities, some from queries
* [[G1G1 Activity testing#Activity list]] queries for activity pages in the Activities/G1G1 activity group
* [[Activity queries]] has a useful query of all activities, and others
* [[Activity query examples]] has more queries

Adapting activities and their templates to use Semantic Forms would make it easier to
* maintain the [[Activities]] page
* show the status of activities in various activity packs
* query for things like activities that don't have a translation status.

==== Activity update? ====
The XO's [[Software update]] panel (new in release [[8.2.0]]) consults wiki pages like [[Activities]] and [[Activities/Joyride]] to figure out whether a newer version of an activity is available. Perhaps these pages could be generated by querying for the properties of activities, but the resulting HTML has to match a rigorous [[Activity microformat]].

==== Other things to do ?? ====
People want changes but what exactly?
* Unify the [[Olpcboxes|OBX box]] and semantic properties &mdash; more details on [[/Activities]] subpage
* Unify [[Creating_an_activity]] and the new [[Form:Activity]]?
* Generate tables of activities?
** Replace the Bundled/Core/Extra distinctions with properties?

=== For releases ===
The [[Releases]] page had duplicated summary information for each release.
In September 2008 this info was annotated in each release page (see e.g. [[8.1.0]]), so you could query for it. Some queries:
* [[Future releases]] queries for [[Property:Status|Status]] NOT "released", i.e. future releases.
* [[Future releases]] queries for [[Property:Release date|release date]] and/or [[Property:Target date|target date]] showing the information on a timeline.
* [[Release notes]] queries for [[Property:Status|Status]] "released" sorted by Release_date, i.e. past releases.
* [[What release am I running?]] has a query displaying the [[Property:Build number|build number]] first.

Also see [[Releases-test]] page.

==== ISSUE: Merging release page and "Release notes" ====
As of September 2008, most releases have a page that only contains the semantic info, and a separate Release_notes/xxx page with all the information about the release, for example [[8.1.1]] and [[Release notes/8.1.1]]. This is a hassle for editors who have to maintain two pages and the link between them, and for users who follow links to a build and then have to go to its release notes.

[[User:CScott]] experimented with moving the semantic info for 8.1.0 into [[Release notes/8.1.0]], but that means in a query of e.g. build numbers and firmware versions the "release" appears as Release notes/8.1.0. And it's strange for a page named "Release notes/8.1.0" to make semantic statements like "my ECO is xyz", "my firmware version is nnn", etc.

[[User:Skierpage]] thinks the solution is to have pages named e.g. [[9.1.0]] with the semantic information in a "Standard information" section. Then as release note information becomes available, editors add it to this page in additional sections and categorize the page as [[:Category:Release notes]]. There is no compelling need for release notes to be subpages of "Release notes". There is unlikely to be title conflict between release numbers and existing pages.

[[User:CScott]] also removed past release info from [[Releases]] and put it in [[Release notes]], turning the former into [[Future releases]]. This also shows the distinction between releases and release notes is not useful. As a release page firms up, it gets release note information.

==== Info for each release ====
Here are some properties that releases may have, based on the [[Releases]] page and e-mail message "Re: [sw-eco] q2e11 firmware for 8.1.2 ECO" to devel@laptop.org of 2008-07-15:
* [[Property:Status]]: string, restricted to values like "nascent", "gathering requirements", "released".
* [[Property:Primary maintainer]]: usually someone with a wiki page
* Note the Release Notes wiki page can be derived from the release name, it's always Release_notes/''N.N.N''
* ECO: a release uses the more general [[Property:Is part of]] to link to an ECO's wiki page
* Primary objectives: a release can have multiple [[Property:Has objective]] values.
* [[Property:Lead customer]]: wiki page, can be the country [[Peru]] or the organization [[OLPC_Peru]].
* [[Property:Build number]]
** Build URL: In theory for a released release this can be derived from Build_number, it's always http://download.laptop.org/xo-1/os/official/''NNN''. But to make it easier and future-proof, it's an explicit separate [[Property:Download URL]].
* Schedule: Each release page can have a [[Property:Target date]] if it's still planned and should have a [[Property:Release date]] when its status becomes "released". The release's page may have additional details such as a schedule URL, Created date, or Date documentation posted, these aren't properties.
* a [[Property:firmware]] wiki page like [[OLPC Firmware q2e15]]. ''or is this a property of the build''?
* a [[Property:Release notes]]. Release ''N.NN.N'' 's notes are currently the page <nowiki>[[Release notes/</nowiki>''N.N.N'']] , but as of SMW version 1.2 in September 2008 you can't modify a page property to make a different page link.

===== Future releases vs. released releases =====
A future release has
* <nowiki>[[Build number::999]]</nowiki> &mdash; it doesn't have a known build
* <nowiki>[[Status::</nowiki>''anything but Released'']]
* <nowiki>[[Target date::</nowiki>''some date'']] and no <nowiki>[[Release date]]</nowiki>

A release that's happened has
* <nowiki>[[Build number::</nowiki>''NNN'']]
* <nowiki>[[Status::Released]]</nowiki>
* <nowiki>[[Release date::</nowiki>''some date'']] and no <nowiki>[[Target date]]</nowiki>

==== Release info issues ====
* If Greg wants to re-display additional status information in the queries on the Releases page like "Candidate build is out - Join the test effort!", we could add [[Property:More info]] to release pages and display in queries.
* The [[Releases]] page used to show
** link to release notes
** URL for build directory
** each objective in a bulleted list
: Displaying these in the queries would require creating a query results template.

==== ECOs? ====
Each ECO is associated with a release and has info like:
* Title: string (not always a release)
* Date proposed: date
* Target date: date, sometimes fuzzy like "week of 2008-03-02"
* Trac items: multiple bug numbers (and manual copy of their text)
* Date released
* Priority: "normal", "high", with string
* Champion: usually someone with a wiki page.
* Reviewers: wiki text, often includes "triage team" and/or "Testing: [[1_Hour_Smoke_Test|1 hour smoke]]"
* Special testing required: string
* Rollout: "Manufacturing" and "Field"
* Checklist: wiki page for URL, usually ''<ECO page_name>''_Checklist

It's unclear if any of this is worth annotating. Maybe a table of ECOs with their build and firmware, but the release is tied to an ECO, not vice-versa.


==== Reusing release values ====
{{SERVERNAME}} uses three methods to display a changing value like ''The release candidate'' on multiple pages without having to update each one.

* Mention one of the sub-templates of [[Template:Latest Releases]], such as [[Template:Latest_Releases/stable]]
: latest release is ==> {{Latest_Releases/stable}}

* Transclude a subpage with the information, such as [[Friends in testing/current image number]] or [[Friends in testing/current image stream]]
: current testing stream & release is ==> {{:Friends in testing/current image stream}} & {{:Friends_in_testing/current_image_number}}

* Use SMW's #ask or show function to display a property from a page, such as [[Property:Current image number for testing]] or [[Property:Current image stream for testing]]
: current testing stream & release is ==> {{#ask: [[Friends in testing/current image stream]] | ?Current image stream for testing=}} & {{#ask: [[Friends in testing/current image number]] | ?Current image number for testing=}}
: #show should also work... {{#show: Friends in testing/current image stream ?Current image stream for testing}} & {{#show: Friends in testing/current image number ?Current image number for testing}}
::As of 2008-08-07 this last semantic approach is implemented ''completely the wrong way'', these should be generic properties [[Property:Stream]] and [[Property:Build]] associated with a descriptive page like [[Testing build]] or [[Stable release]], not specific properties on specific page names. -- [[User:Skierpage|Skierpage]] 10:27, 12 August 2008 (UTC)

=== For events ===
Annotate [[:Category:Events|events]], [[:Category:Jam|jams]], and [[:Category:Meetings|meetings]] with [Property:Start date]], and then other pages can query to get a list or timeline of future pages. See the queries on [[Jams]] and [[Events#Upcoming events on wiki.laptop.org ]]

* Also give events a [[Property:End date]]; this is optional for meetings and jams that are usually one day.

* Additional properties appropriate for events are [[Property:Has location city]] and [[Property:Has location country]]

* Can also use [[Property:Cooordinates]] to annotate where an event is. See, e.g. [[OLPC Switzerland/Meeting October Bern]]. Unfortunately it seems that displaying multiple events as markers on a map requires additional extensions.

=== For software features ("Feature roadmap) ===
2008-12-12 the [[Feature roadmap/Archive/pre-9.1.0 |static feature roadmap]] was split into subpages, and [[Feature roadmap]] queries these. [[Features-test]] has other sample queries.

Each feature is a subpage of Feature roadmap/ ; each uses [[Template:Feature tracking]] to add semantic properties to itself and display a standard appearance.

[[/Archive]] has original discussion and planning of the feature.

==== TODO ====
* [[Property:Short name]] is redundant, derive it from page name. (is it even used?)
* [[Property:Priority]] should be set to something if not explicitly set.
* see if category assignment can be put in a <nowiki><noinclude</nowiki> so that a format=embedded query doesn't get category assignments.
* Make [[9.1.0]] page query for pages with [[Property:Target for 9.1]].
* Add a query to each deployment page showing its requested features.
* Once layout settles down, use a template to display query results, which can:
** Remove "Feature roadmap/" in front of every name.
* ''Decide?'' Add <nowiki>__NOFACTBOX__</nowiki> to feature pages so they don't have a confusing factbox following the table?
* ? Maybe remove the period from [[Property:Target for 9.1]] as it causes weird breakage in queries (have to put a space in front of it.

== Where semantics ''could'' be used ==

=== For translations? ===
The main translation infrastructure on the wiki requires that for every page that has translations you maintain a little subpage linking the different translations together. For example, [[Software components]] has [[Software components/translations]] that lists
<nowiki>{{translationlist | es | it | ja | ko | orig=en }}</nowiki>

As an alternative, the [http://semantic-mediawiki.org Semantic-MediaWiki.org site] uses a [http://semantic-mediawiki.org/wiki/Template:Docu "Docu" template] that queries to find all other pages based off the same master page and displays a translation bar linking to them. The existing [[Template:translation]] could probably be adapted to work with semantics, since the information that this query needs is already in pages, such as:
<nowiki>{{ Translation | lang = de | source = Translating/HowTo | version = 54321 }}</nowiki>
The benefit is no one has to maintain the "Page foo/translations" page, and there's only one template to use, instead of Translation and Translation'''s'''. (The existing [[Template:Translations]] would call this, defaulting to lang=en and source=<nowiki>{{PAGENAME}}</nowiki>.)



=== For content repositories? ===
[[User:Lauren]] and others created lots of pages in [[:Category:Content Repository]] about various online libraries and collections.
These pages have information such as
* Format
* Scope
* Multilingualism
* Quality
which ''could'' be made into semantic annotations for properties with these names, so you could query "Show me the name, url, and formats of all content repositories of topic::''music'' with quality::''high''.

These seems to come from [[Template:Content item]] (maybe there's a "Create content item" link or option somewhere?). However, skierpage looked at a dozen of these pages in September 2008 and in most of them these fields aren't filled out.

==To Do list==

=== Semantic Google maps ===
To embed google maps in the wiki with locations of projects/deployments/events and with links to appropriate wiki pages, we need
* Create [[Property:Coordinates]] &mdash; ''done'', pages that use it get a "service links" to Google maps for free (click the (?) button, click the link).<br />Still '''TO DO''':
* Install http://www.mediawiki.org/wiki/Extension:Semantic_Google_Maps
* Get a Google Maps API key.
* Add Coordinates to [[Form:Deployment]] and [[Template:Deployment]], also to event pages.
* Query for these to show maps of deployments and events
Meanwhile, people have [http://maps.google.com/maps/ms?f=q&hl=en&ie=UTF8&cd=1&om=1&msa=0&msid=114558805698125207804.000440a3d84313e9c1ecd&ll=-18.229351,-47.724609&spn=85.325239,-67.300873&source=embed made their own maps on Google]<br />-- [[User:Skierpage|Skierpage]] 02:55, 1 October 2008 (UTC)

===Easy Fixes ===
;(ie just edit a little bit of code)


;Auto generate templates:
:Make template an activity and edit with form
:Move around the <no include> tags
::But when empty it should show something
:Make a tag that says this is not semantic stuff
::Ignore semantics in a specific name space
::The wiki already ignores semantic annotations in the Template: namespace. -- [[User:Skierpage|Skierpage]] 03:01, 1 October 2008 (UTC)


;Alt text not working in templates:
:Feature part of [[Tests/Sugar_Control_Panel/About_Me/Color_Change]]
:: Actually this is hard to fix in SMW. If something is of Type:Page, you can't provide alt text to display in query results instead of the page link, even though it's trivial to do in wiki markup. -- [[User:Skierpage|Skierpage]] 03:01, 1 October 2008 (UTC)

; Add new types
::* It's easy to add a property that has some built-in type (like <nowiki>[[Has type::Text]]</nowiki> and restrict it to certain values and maybe control its format.
::* It's possible to add a new "linear" type that converts between different units , e.g. [http://sandbox.semantic-mediawiki.org/wiki/Type:Area a Type;Area]
::* it's hard to add other kinds of types, it requires writing PHP code.
::* -- [[User:Skierpage|Skierpage]] 10:42, 31 July 2008 (UTC)
:Time duration
:: If you want auto-conversion between e.g. weeks and days and seconds, copy what you want from [http://semanticweb.org/wiki/Type:Time] -- [[User:Skierpage|Skierpage]] 10:42, 31 July 2008 (UTC)

:User
:: Not sure what this means. If it's links to [[User:skierpage]] then maybe just create Property:User of type:page.

:Trac bug number
:: This is available as [[Property:Trac bug number]] of type:Number. You should be able to use [http://semantic-mediawiki.org/wiki/Help:Service_links Service links] and templates in query results to get this to display as a link. But numbers appear with a comma for the thousands separator. Could instead make it Type:URL and you use a template to fabricate the URL, but then it would appear as a long URL in query results. It might be possible to write PHP code to create a Type:Trac that displays appropriately, similar to how the <nowiki><trac>4321</trac></nowiki> code displays.

:Image
:: Just some property of Type:Page (the default), in most cases SMW do the right thing and display the image .

:Template?
;Make the free text box larger.

;When creating a template, you should be able to create properties in that window as well as use already created properties.


;Way to 'prettify' links when used in SMW properties with a "Page" type.
:Example: [[Tests/Sugar_Control_Panel/About_Me/Color_Change|Color Change]] instead of [[Tests/Sugar_Control_Panel/About_Me/Color_Change]].
:: See [[#Suggestions_for_test_cases]]. Maybe have a "Brief name" property and display that while linking to the full page name. Or, in queries use format=template and in the template use a parser string function to change the title from Tests/Sugar_Control_Panel/About_Me/Color_Change. Or, use categories to identify the hierarchy. You risk collision if the page title is just '''Color change''', so you could have a little "TC" prefix, just [[TC/Color Change]] or a pseudo-namespace [[TC:Color_change]]


;Translating Property names
:Nathany on #cc


; When making a template add a more organized presentation of properties

===Complex fixes ===
;(ie require creating a new extension)


; Something in between a list of specific allowed values and free text
:I want to be able to have the equivalent of an other field
:: One approach: have two properties like Property:Version and Property:Version_more that you always display together, the first has restricted values, the other is text. Another is to use Type:Page and have pages for the allowed values. So not-allowed values "work", but stand out in red.


; Way to automatically email users who maintain pages


; Automatically populate data
:ex page last updated case
:: SMW 1.1 can't query on or display such metadata. I think other extensions like DPL can.
:Way to pull %translated from pootle
:: Could have a bot that gets this information and populates wiki pages with it.

== Semantic annotations ==
The wiki has the [[wikipedia:Semantic MediaWiki]] extension installed, the thing to do is use it appropriately.

=== Successful rollout suggestions ===
* Deliver benefits early.
** To a casual editor, SMW is just more markup, more stuff to learn, an ugly factbox on pages, more "Semantic Web 3.0" hype. So find use cases that deliver obvious benefits early
* Don't create lots of properties and spend time annotating lots of pages until you have use cases for them. A person reading one wiki page after another does not need semantic annotations.
* It's fine to convert templates to make semantic annotations, since you get this "for free"



== {{SERVERNAME}} issues ==
Use [[Template:SMW issue]] to note a problem on any page, it'll show up on the [[Property:SMW issue]] page.

=== Template conversion ===
* Use arraymap to turn lists of things into multiple property assignments.
* Use Semantic Forms... (not sure about it)
* Beware, people take advantage of wiki markup to stick all kinds of text inside templates. Maybe have an "fieldname extra info" field for arbitrary text.

=== Generic names ===
Should [[Property:Test objective]] be a generic name, or specialize it to [[Property:Test case objective]] ? skierpage's bias is to use generic names, but document on their property page what templates and pages use them.

[[Category:Semantic MediaWiki]]

== How tos ==

=== Modify or remove a property ===

Summary:
# Edit the template the form fills in
# edit the form
# edit queries that use the property

Here's an example from [[User:Skierpage]] of removing [[Property:Contact person]] from deployment pages.

A human being should have documented the [[Property:Contact person]] page with:
: ''Template:Foo, filled in by Form:Bar, may set this property.''

1. Instead, if you edit a deployment page you can see
{{Deployment
...
|contact person=user:sbuchele

therefore [[Template:Deployment]] sets this property. So I edited the template and removed the table row that sets this property. Changing a template should (and did!) eventually update pages invoking it like [[OLPC_Ghana]]; if you don't want to wait you would Edit & Save each deployment page to get it to happen faster.

2. To modify the form, you could guess it's called [[Form:Deployment]], or use [[Special:Allpages]] to show all pages in the Form: namespace, or look at [[:Category:Deployments]] and see <nowiki>[[Has default form::Form:Deployment]]</nowiki> which makes the "edit with form" tab appear.

I'm not an expert in Semantic Forms, so I just edited [[Form:Deployment]], deleted the "Contact Person" part of it, and it seemed to work.


3. Then, edit queries that show Contact person and delete the
| ?Contact person
line. I did so on the [[Deployments]] page.

Revision as of 15:14, 13 December 2008

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=Semantic_MediaWiki&oldid=186180"