Difference between revisions of "Solution Compatibility Roadmap"

Latest revision as of 17:28, 27 October 2015

What makes a compatible solution?

In order to be compatible with the GPII Auto Personalisation from Preferences (APfP) a solution must:

• be known to the GPII as a solution for specific user preferences
• have known settings and how they map to preferences described as common terms
• have a known way to be launched and closed

This is achieved by providing a few configurations files to the GPII that declare these details. The GPII is then able match user preferences (possibly including context) and launch the solution with optimal settings for the user when they identify themselves.

Roadmap

Common preference terms

It is vital to manage the large number of possible settings, especially as some have different names for the identical concept and others with the same name are actually different concepts. In addition the range of values allowed may or may not vary between common terms. The Preference Term Database (PTD) is the GPII's tool where all solutions settings are registered to provide a manageable database of terms. All settings for solutions are added to the PTD

Solution declaration

A solution's operation is described to the GPII using JSON declarative 'code' entered into a file which holds all the solutions for a specific platform (eg Windows, Android). This describes how to launch / kill the solution and specific settings and the transforms that map to them from common preference terms.

Steps for making a solution GPII compatible

For each solution to be be made compatible the following steps will be performed (work is being lead by the Tiger Team)

Workflow

1. Select a solution from above Roadmap - Let the Tiger Team know you are working on it
2. Create a tracking Jira to discuss issues etc. Use the Tiger Team project and AutoPersonalisationCompat component. See this explanation of Jira workflow
3. Fork and pull the GPII/universal repo
4. Create a feature branch to work on. Use Jira number in the branch name
5. Work through the details below
6. Discuss and track on the Jira, list or IRC as required. Use "@User" to notify someone
7. Track status in the above roadmap
8. Make a pull request and update Jira status to Pull Request
9. Wait for review by the Architecture team and work through any fixes
10. Close Jira and update Roadmap

Work detail

1. Identify key contact person(s) and contact them.
   1. Permissions - ownership - mgmt etc
   2. Technical - launch, settings access, meaning of settings
   3. Let them know about the GPII, DSpace, universal listing etc.
2. Register and align the preferences/settings in the Preference Terms Definitions Registry (PTD)
   1. Developer might do but MUCH MUCH easier for us to do we have familiarity with the PTD contents
   2. Developer should participate because they know what their terms mean
   3. See details below
3. Modify the way a product handles settings (optional)
   1. Define/Save preferences to better match the GPII
   2. Prefer dynamic settings refresh - to allow live use of externally changed settings
4. Decide how to read / write settings
   1. Use an existing settings handler - eg ini, JSON.
   2. Create new generic settings handler or write solution specific code
   3. Create a transcoding/un-packing tool for binary and other compressed formats.
5. Create a solution entry
   1. Add Solution description file in testData/solutions/solutionsDescription
   2. lifecycle declaration and Setting transforms in appropriate platform file in testData/solutions
6. Register solution but adding to testData/deviceReporter/installedSolutions.json file
7. Perform Testing
   1. Create a test user profile file to exercise settings when user logs in. testData/preferences/<solution>N
   2. Create Tests FIXME - tests
8. Document
   1. Solution specific notes - in DSpace
   2. Generic documentation for others

Processing preference terms in the PTD

The PTD tool is used to keep a list of common preference terms and their alias as used in solutions. Here's how to process each of a solutions settings to ensure they are captured in the PTD.

1. Get a lists of the settings and their parameters valuespace (possible values)
2. find their counterpart in the Preference Terms Dictionary (eg use the filter)
3. IF found (with SAME definitions and SAME valuespace)
   1. Register them as an alias -- and note the common preference term
4. IF NOT found (AND it is a term that might be used by other solutions)
   1. Create a common preference term
   2. Register the term as an alias
5. IF NOT found and very low or no possible use to other apps as one of their settings (with same definition and value space
   1. Then just enter as a new term using their format

Helpful Links

1. GPII/universal on GitHub
2. TigerTeam project in Jira
3. GPII Core Infrastructure - How the GPII Auto Personalisation form Preferences works when a user logs in
4. Building A Simple Solution Example simple solution
5. Authoring Solutions Tutorial detailed instructions for a solution entry
6. Architecture - Available transformation functions - Tutorial on Value transformation
7. http://wiki.fluidproject.org/display/docs/Model+Transformation - Fluid Infusion Framework (Transformation)
8. https://www.atlassian.com/git/ - Advanced git tutorial