Firefox/Projects/PlacesQueryAPIRedesign: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
== Places Query API  ==
= Places Query API Redesign =
*'''Development Status:''' - STALLED  (06/24/2010)
*'''Feature Testing:''' - NOT STARTED (06/24/2010)
*'''Team:''' Marco Bonardo (dev), ashughes (qa)
*'''Tracking Bugs''': {{bug|522572}}


Create a sensible, easy to use Query API for Places for Firefox.next & Jetpack. This API should make it possible to do targeted queries against history and bookmarks with a minimum of code.  
=== Feature Description  ===
Create a sensible, easy to use Query API for Places for Firefox.next & Jetpack. This API should make it possible to do targeted queries against history and bookmarks with a minimum of code.  


== Goals/Use Cases  ==
= [[#Feature Release Readiness Assessment_Details|Feature Release Readiness Assessment]] =


*An elegant and easy to use API. Fx devs, Jetpack and extension developers will all benefit.
The table below provides a top level go/no go assessment of whether the feature is release ready for the given milestone.
*allows us to prototype the new ui for Fx.next
*<strike>'Pluggable' results handling</strike> Easy wrappable querying object and results<br>
*Focus on JS usage
*<strike>Paging Support - Sounds like a great use of Generators!</strike> dropped, there is no perf gain, can be a follow-up<br>
*Fetch individual record by Id or other property


<strike>(After talking to the Labs guys about Weave, we should try to provide a plugin-interface whereby you can allow a developer to keep track of and index random JSON objects.</strike>
{| class="fullwidth-table"
|-
! Milestone
! Assessment
|-
| [[#Beta1]]
| '''NO GO'''
|-
| [[#Beta2]]
| N/A
|-
| [[#Beta3]]
| N/A
|}


<strike>Dan Mills has example code that was created for the people store. Link coming soon.)</strike>
[[#Feature_Description|top]]
= [[#Feature_Documentation_Details|Feature Documentation]] =


== Non Goals  ==
{| class="fullwidth-table"
|-
! Item
! Description
! Status
|-
| [[#Project_Wiki]]
| Wiki Links to all feature related entries
|
|-
| [[#Developer_Links|#Developer_Links (blogs)]]
| Developer links to feature related sites
|
|-
| [[#Other_Docs]]
| Web links to feature related sites
|
|-
| [[#Developer_QA_Review]]
| Details from developer and qa discussions regarding feature test strategies and issues.
|
|}


*Tailoring the API to tree views
[[#Feature_Description|top]]
*Creating the perfect API (lets iterate)
*Create an abstract datastore<br>
*<strike>Intended as a snap-in replacement of the current API</strike> Future follow-up through a live-updating wrapper<br>
*Wrap current sync and XPCOM API


== Status  ==
= [[#Feature_Bug_Management_Details|Feature Bug Management]] =


*Old prototype landed in Jetpack 0.8, currently being revised<br>
{| class="fullwidth-table"
*Team
|-
**'''API''': ddahl, mak
! Item
**'''UX/UI''': not required so far, future users could though
! Description
*Implementation bugs: {{bug|522572}} {{bug|545700}} {{bug|531940}} {{bug|543888}}
! Status
*Next Steps
|-
**Iterate the feel of the API with the Places team and other interested developers. Ideas and feedback are encouraged. Build working examples to encourage feedback.
| [[#Bug_Tracking]]
| Top level bugs tracking feature 
|
|-
| [[#Bug_Verification]]
| Feature bugs that need verification 
|
|-
| [[#Bug_Triage]]
| Links triage bug tasks 
|
|}


== Timeline / Milestones  ==
[[#Feature_Description|top]]


*2010/02 Landed in Jetpack 0.8
= [[#Feature_Test_Items_Details|Feature Test Items]] =
*2010/03 Work on "skeleton" API design with Marco
*2010/05 New redesign, collecting feedback and proceeding.<br>


== Delivery Requirements  ==
The table below provides a breakdown of all feature items that should be covered and how they will be tested. Not all items will be covered by internal QA team members.


*This is purely additive.
{| class="fullwidth-table"
*Coordination with Jetpack as this should be coded once, checked into places and imported into Jetpack's implementation.
|-
! Test Item
! Description
! Covered By
! Status
|-
| [[#API]]
| Changes to the API
| Developer testing, QA regression testing, Jetpack developer testing
|
|-
| [[#Localization]]
| Feature localization
|
|
|-
| [[#Accessibility]] 
| Feature accessibility
|
|
|-
| [[#Plugins]]
| Plugins compatibility 
|
|
|-
| [[#Addons]]
| Addons compatibility 
|
|
|-
| [[#Topsites]]
| Top internet sites compatibilities 
|
|
|}


== Constraints  ==
[[#Feature_Description|top]]


*Final implementation should use only Async Storage APIs
= [[#Feature_Tests_Details|Feature Tests]] =
== [[#Automated_Tests_Details|Automated Tests]] ==
{| class="fullwidth-table"
|-
! Item
! Description
! Status
|-
| [[#Developer_Tests]]
| Links to automated developer tests
|
|-
| [[#Mozmill_Tests]]
| Links to automated mozmill feature test cases 
|
|}


== Dependencies  ==
== [[#Manual_Tests_Details|Manual Tests]] ==
{| class="fullwidth-table"
|-
! Item
! Description
! Status
|-
| [[#Smoke_Tests]]
| link to smoke tests
|
|-
| [[#Regression_Tests]]
| link to BFT and/or regression tests
|
|-
| [[#Functional_Tests]]
| link to FFT and/or complete functional tests
|
|}


== Testing  ==
[[#Feature_Description|top]]


*Comprehensive xpcshell tests
= [[#Community_Test_Events_Details|Community Test Events]] =
*<strike>Example/Documentation style Browser Chrome tests</strike> Not for now, when treeviews will use this.<br>
{| class="fullwidth-table"
*TDD
|-
! Item
! Description
! Status
|-
| [[#Testdays]]
| Links to test day event results for feature
|
|-
| [[#Bugdays]]
| Links to bug day event results for feature
|
|-
| [[#Meetups]]
| Links to Meetup events for feature
|
|}
[[#Feature_Description|top]]


== Related Projects  ==
= [[#Feature_Documentation|Feature Documentation Details]] =
== Project Wiki ==
* [https://wiki.mozilla.org/Firefox/Projects/PlacesQueryAPIRedesign Project page]


*Jetpack<br>
[[#Feature_Documentation|top]]


== Additional Details  ==
== Developer Links ==
* Provide links to all feature related developer links to blogs and other internet sites


The initial API "sketches" are here: [https://wiki.mozilla.org/Firefox/Projects/PlacesQueryAPISketches]  
[[#Feature_Documentation|top]]


Faaborg has been mocking up designs and putting a lot pf thought into the UX: http://blog.mozilla.com/faaborg/2009/10/13/browsing-your-personal-web
== Other Docs ==
* Provide links to all feature related developer links to blogs and other internet sites


== Inspiration  ==
[[#Feature_Documentation|top]]


Links to code we should study...  
== Developer QA Review ==
* Do we have automated tests for the feature?
** Not yet
* What do they cover?
**
* What do they not cover?
**
* How well do they cover the feature?
** Feature is completely covered by these tests
* What are the important areas we should focus on?
** Regression testing Places and Jetpack
* What are the dependencies?
** Final implementation depends on [https://wiki.mozilla.org/Firefox/Projects/Async_Places_containers Async Places Containers]
* What is our comfort level with this feature in its current state?
** On track but progress blocked by developer focus on ABOUT:HOME project
* What feedback would you like from QA?
** Regression testing of Places features once it lands


==== Gloda  ====
[[#Feature_Documentation|top]]


Gloda: [https://developer.mozilla.org/en/Thunderbird/gloda]  
= [[#Feature_Release_Readiness_Assessment|Feature Release Readiness Assessment Details]] =


facet.js: [http://mxr.mozilla.org/comm-central/source/mailnews/db/gloda/modules/facet.js]
== Beta1 ==
* Not ready, will not land
== Beta2 ==
* May be ready for this milestone
== Beta3 ==


Gloda Fundamental Attribute provider: [http://mxr.mozilla.org/comm-central/source/mailnews/db/gloda/modules/fundattr.js]
= [[#Feature_Bug_Management|Feature Bug Management Details]] =
== Bug Tracking ==
* Top level bugs tracking feature. Include any relevant bug queries that are helpful for tracking feature status.


Explicit Attribute Provider: [http://mxr.mozilla.org/comm-central/source/mailnews/db/gloda/modules/explattr.js]  
{| class="fullwidth-table"
|-
! Query Name
! Description
|-
| {{bug|522572}}
| Top-level tracking bug
|}
 
[[#Feature_Bug_Management|top]]


FacetView: [http://mxr.mozilla.org/comm-central/source/mail/base/content/glodaFacetView.js]
== Bug Verification ==
* Feature bugs that need verification 


== Current Sketches  ==
[[#Feature_Bug_Management|top]]
<pre class="brush:js;toolbar:false;">function callback(results) {
  // results is a simple array of ResultItem, it's pretty easy to wrap it
  // if more complex management is needed.
  if (results.length == 0)
      dump("En empty results array indicates last results push\n");
  else
      dump("Collected " + results.length + " results this turn\n");
}


// Results are pushed to the callback as soon as they are available.
== Bug Triage ==
new PlacesQuery([object]QueryConf, [function]callback, [scope]thisObject);
* Bug triage information


// It's possible to pass multiple QueryConf objects, results will be merged
[[#Feature_Bug_Management|top]]
// based on the .merge attribute of each config.
// First query results are always unioned.
// In case of multiple queries, sort, group and limit of the first query will
// be used for the global result.
new PlacesQuery([QueryConf1, QueryConf2], callback, thisObject);


// It's possible to create the query, but run it later.
= [[#Feature_Test_Items|Feature Test Items Details]] =
let query = new PlacesQuery(QueryConf);
query.execute(callback, thisObject);


/* The query can be so configured:
== API ==
*
* Regression testing of existing Places features (Bookmarks, History, Library, etc)
* _QueryConf_ = {
* Cross-testing with Jetpack implementation will be required
*  phrase: string.
*          Containing this string in either title, uri or tags.  Case
*          insensitive.  Can use ^ and $ to match at beginning or end.
*  host: string.
*        Containing this string in the host.  Case insensitive.
*        Can use ^ and $ to match at beginning or end.
*  uri: string.
*        Containing this string in the uri.  Case insensitive.
*        Can use ^ and $ to match beginning or end.
*   annotated: array of strings.
*              With these annotations (Either page or item).
*  bookmarked: object
*  {
*    tags: array of strings.
*          Tagged with these tags.
*    at: object
*    {
*      folder: number.
*              Inside this folder. (non-recursive)
*      position: number.
*                At this position. (relative to folder).
*                If undefined or null matches all children.
*    }
*    id: number.
*        Bookmarked with this id.
*    when: object
*    {
*      begin: optional Date object
*              Bookmarks created after this time (included).
*              Defaults to epoch.
*      end: optional Date object
*            Bookmarks created before this time (included).
*            Defaults to now.
*    }
*    modified: object
*    {
*      begin: optional Date object
*              Bookmarks modified after this time (included).
*              Defaults to epoch.
*      end: optional Date object
*            Bookmarks modified before this time (included).
*            Defaults to now.
*    }
*    onlyContainers: boolean.
*                          Removes any non-container from results.
*                          Default is false.
*    excludeReadOnlyContainers: boolean.
*                                Removes read only containers from results.
*                                Default is false.
*  }
*  visited: object
*  {
*    count: object
*            This is lazily based on visit_count, thus is not going to work
*            for not counted transitions: embed, download, framed_link.
*    {
*      min: optional number.
*            With more than this many visits.
*            Defaults to 0.
*      max: optional number.
*            With less than this many visits.
*            Defaults to inf.
*    }
*    transitions: array of transition types.
*                  With at least one visit for each of these transitions.
*    when: object
*    {
*      begin: optional Date object
*              With visits after this time (included).
*             Defaults to epoch.
*      end: optional Date object
*            With visits before this time (included).
*            Defaults to now.
*    }
*    excludeRedirectSources: boolean.
*                            Removes redirects sources from results.
*                            Default is false.
*    excludeRedirectTargets: boolean.
*                            Removes redirects targets from results.
*                            Default is false.
*    includeHidden: boolean.
*                    Includes also pages marked as hidden.
*                    Default is false.
*    allVisits: boolean.
*                Returns all visits ungrouped.
*                Default is false, that means visits are grouped by uri.
*  }
*  sort: object
*  {
*    by: string.
*        Either "none", "title", "time", "uri", "accessCount", "lastModified",
*        "frecency".  Defaults to "none".
*    dir: string.
*          Either "asc" or "desc".  Defaults to "asc".
*  }
*  group: string.
*          Either "tags", "containers", "days", "months", "years" or "domains".
*          Defaults to "none".
*          NOTE: Not yet implemented.
*  limit: number.
*          Maximum number of results to return.  Defaults to all results.
*  merge: string.
*          How to merge this query's results with others in the same request.
*          Valid values:
*          - "union": merge results from the 2 queries.
*          - "except": exclude current results from the previous ones.
*          - "intersect": only current results that are also in previous ones.
* }
*
* NOTE: In case of multiple queries, sort, group and limit of the first query
* will be used for the global result.
*
*
* The query returns an array of these simple ResultItem objects
* ResultItem {
*  pageId: the place_id of the page, useful for external linking of resources
*  uri:
*  title:
*  host:
*  accessCount: visit count for pages, aggregated or null for containers
*  time: visit date, aggregated or null for containers
*  icon: url of the icon
*  sessionId: visit session or null if not available
*  itemId: bookmark id or null if not bookmarked (see isBookmarked)
*  isBookmarked: whether this is bookmarked or not
*  dateAdded: bookmark creation Date() or null if not bookmarked
*  lastModified bookmark modification Date() or null if not bookmarked
*  parentId: bookmark folder id or null if not bookmarked
*  tags: string of tags
*  tagsArray: array of tags
*  bookmarkIndex: position of the bookmark in his container or null
*  frecency:
*  visitId: id of the visit or null
*  referringVisitId: id of the originating visit or null
*  referringUri: uri of the originating visit or null
*  transitionType: transition of this visit or null
*  type: old container implementation type
*  readableType: "bookmark", "container", "separator", "visit", "page"
*  query: if this is a container will return a new PlacesQuery for contents
* }
*
*/


// EXAMPLES (not all of them work, they are supposed to show the conf)
== Localization ==
* Details of feature localization test requirements


// Bookmarks toolbar.
[[#Feature_Test_Items|top]]
new PlacesQuery({ bookmarked: {
                      folders: [PlacesUtils.bookmarksToolbarFolderId]
                  },
                  group: "container"
                });


// History menu.
== Accessibility == 
new PlacesQuery({ visited: {},
* Details of feature accessibility test requirements
                  sort: { by: "time", dir: "desc" },
                  limit: 10
                });


// Start-of-awesomebar (still missing adaptive, keywords, ...).
[[#Feature_Test_Items|top]]
new PlacesQuery({ phrase: "someword",
                  sort: { by: "frecency", dir: "desc" },
                  limit: 12
                });


// Folder picker.
== Plugins ==
new PlacesQuery({ bookmarked: {
* Details of plugins compatibility test requirements
                      at: { folder: PlacesUIUtils.allBookmarksFolderId }
                      onlyContainers: true,
                      excludeReadOnlyContainers: true
                  },
                  group: "container"
                });


// Most recent bookmarks.
[[#Feature_Test_Items|top]]
new PlacesQuery({ bookmarked: {},
                  sort: { by: "lastModified", dir: "desc"}
                  limit: 5
                });


// Most recent tags.
== Addons ==
new PlacesQuery({ bookmarked: {},
* Details of addons compatibility 
                  group: "tags",
                  limit: 5
                });


// Left pane query.
[[#Feature_Test_Items|top]]
new PlacesQuery({ bookmarked: { folders: [PlacesUIUtils.leftPaneFolderId] },
                  annotated: ["Places/OrganizerQuery"]
                  group: "containers"
                });


// Downloads
== Topsites ==
new PlacesQuery({ visited: {
* Details of top internet sites test requirements
                      transitions: [PlacesUtils.history.TRANSITION_DOWNLOAD],
                      includeHidden: true,
                      allVisits: true
                  },
                  sort: { by: "time", dir: "desc" }
                });


// Visited bookmarks containing either "foo" or "bar".
[[#Feature_Test_Items|top]]
new PlacesQuery([
    { phrase: "foo",
      bookmarked: {},
      visited: {}
    },
    { phrase: "bar",
      bookmarked: {},
      visited: {}
    },
);


= [[#Feature_Tests|Feature Tests Details]] =
== [[#Automated_Tests|Automated Tests Details]] ==


// Visited bookmarks containing "foo", but not "bar".
=== Developer Tests ===
new PlacesQuery([
* Links to automated developer tests
    { phrase: "foo",
      bookmarked: {},
      visited: {}
    },
    { phrase: "bar",
      bookmarked: {},
      visited: {},
      merge: "except"
    },
);


// Visited bookmarks containing "foo" and "bar".
[[#Feature_Tests|top]]
new PlacesQuery([
    { phrase: "foo",
      bookmarked: {},
      visited: {}
    },
    { phrase: "bar",
      bookmarked: {},
      visited: {},
      merge: "intersect"
    },
);


</pre>
=== Mozmill Tests ===
* [http://hg.mozilla.org/qa/mozmill-tests/file/tip/firefox/testBookmarks Bookmarks]
* History
* Library


== Testing ==
[[#Feature_Tests|top]]
* Most of this will be automated and will not need QA involvement
 
* QA will keep an eye out for regressions during regular release cycles
== [[#Manual_Tests|Manual Tests Details]] ==
* QA will run a testday once this has landed
 
=== Smoke_Tests ===
* [https://litmus.mozilla.org/show_test.cgi?id=11717 Add a bookmark via Main Menu]
 
[[#Feature_Tests|top]]
 
=== Regression_Tests ===
* [https://litmus.mozilla.org/show_test.cgi?searchType=by_category&product_id=1&branch_id=34&testgroup_id=183&subgroup_id=1415 Bookmarks]
* [https://litmus.mozilla.org/show_test.cgi?searchType=by_category&product_id=1&branch_id=34&testgroup_id=183&subgroup_id=1416 History]
* [https://litmus.mozilla.org/show_test.cgi?searchType=by_category&product_id=1&branch_id=34&testgroup_id=183&subgroup_id=1499 Library]
 
[[#Feature_Tests|top]]
 
=== Functional_Tests ===
* [https://litmus.mozilla.org/show_test.cgi?searchType=by_category&product_id=1&branch_id=34&testgroup_id=182&subgroup_id=1432 Bookmarks]
* [https://litmus.mozilla.org/show_test.cgi?searchType=by_category&product_id=1&branch_id=34&testgroup_id=182&subgroup_id=1434 History]
* [https://litmus.mozilla.org/show_test.cgi?searchType=by_category&product_id=1&branch_id=34&testgroup_id=182&subgroup_id=1500 Library]
 
= [[#Community_Test_Events|Community Test Events Details]] =
== Testdays ==
* No testdays planned
 
== Bugdays ==
* No bugdays planned
 
== Meetups ==
* No meetups planned

Revision as of 21:02, 24 June 2010

Places Query API Redesign

  • Development Status: - STALLED (06/24/2010)
  • Feature Testing: - NOT STARTED (06/24/2010)
  • Team: Marco Bonardo (dev), ashughes (qa)
  • Tracking Bugs: bug 522572

Feature Description

Create a sensible, easy to use Query API for Places for Firefox.next & Jetpack. This API should make it possible to do targeted queries against history and bookmarks with a minimum of code.

Feature Release Readiness Assessment

The table below provides a top level go/no go assessment of whether the feature is release ready for the given milestone.

Milestone Assessment
#Beta1 NO GO
#Beta2 N/A
#Beta3 N/A

top

Feature Documentation

Item Description Status
#Project_Wiki Wiki Links to all feature related entries
#Developer_Links (blogs) Developer links to feature related sites
#Other_Docs Web links to feature related sites
#Developer_QA_Review Details from developer and qa discussions regarding feature test strategies and issues.

top

Feature Bug Management

Item Description Status
#Bug_Tracking Top level bugs tracking feature
#Bug_Verification Feature bugs that need verification
#Bug_Triage Links triage bug tasks

top

Feature Test Items

The table below provides a breakdown of all feature items that should be covered and how they will be tested. Not all items will be covered by internal QA team members.

Test Item Description Covered By Status
#API Changes to the API Developer testing, QA regression testing, Jetpack developer testing
#Localization Feature localization
#Accessibility Feature accessibility
#Plugins Plugins compatibility
#Addons Addons compatibility
#Topsites Top internet sites compatibilities

top

Feature Tests

Automated Tests

Item Description Status
#Developer_Tests Links to automated developer tests
#Mozmill_Tests Links to automated mozmill feature test cases

Manual Tests

Item Description Status
#Smoke_Tests link to smoke tests
#Regression_Tests link to BFT and/or regression tests
#Functional_Tests link to FFT and/or complete functional tests

top

Community Test Events

Item Description Status
#Testdays Links to test day event results for feature
#Bugdays Links to bug day event results for feature
#Meetups Links to Meetup events for feature

top

Feature Documentation Details

Project Wiki

top

Developer Links

  • Provide links to all feature related developer links to blogs and other internet sites

top

Other Docs

  • Provide links to all feature related developer links to blogs and other internet sites

top

Developer QA Review

  • Do we have automated tests for the feature?
    • Not yet
  • What do they cover?
  • What do they not cover?
  • How well do they cover the feature?
    • Feature is completely covered by these tests
  • What are the important areas we should focus on?
    • Regression testing Places and Jetpack
  • What are the dependencies?
  • What is our comfort level with this feature in its current state?
    • On track but progress blocked by developer focus on ABOUT:HOME project
  • What feedback would you like from QA?
    • Regression testing of Places features once it lands

top

Feature Release Readiness Assessment Details

Beta1

  • Not ready, will not land

Beta2

  • May be ready for this milestone

Beta3

Feature Bug Management Details

Bug Tracking

  • Top level bugs tracking feature. Include any relevant bug queries that are helpful for tracking feature status.
Query Name Description
bug 522572 Top-level tracking bug

top

Bug Verification

  • Feature bugs that need verification

top

Bug Triage

  • Bug triage information

top

Feature Test Items Details

API

  • Regression testing of existing Places features (Bookmarks, History, Library, etc)
  • Cross-testing with Jetpack implementation will be required

Localization

  • Details of feature localization test requirements

top

Accessibility

  • Details of feature accessibility test requirements

top

Plugins

  • Details of plugins compatibility test requirements

top

Addons

  • Details of addons compatibility

top

Topsites

  • Details of top internet sites test requirements

top

Feature Tests Details

Automated Tests Details

Developer Tests

  • Links to automated developer tests

top

Mozmill Tests

top

Manual Tests Details

Smoke_Tests

top

Regression_Tests

top

Functional_Tests

Community Test Events Details

Testdays

  • No testdays planned

Bugdays

  • No bugdays planned

Meetups

  • No meetups planned
Retrieved from "https://wiki.mozilla.org/index.php?title=Firefox/Projects/PlacesQueryAPIRedesign&oldid=233419"