Firefox/Projects/PlacesQueryAPIRedesign: Difference between revisions

Jump to navigation Jump to search

Firefox/Projects/PlacesQueryAPIRedesign (view source)

Revision as of 21:02, 24 June 2010

4,977 bytes removed ,  24 June 2010
no edit summary
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
Ashughes
Confirmed users
14,525

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/233419"

Navigation menu