1037532 - mozversion should have documentation on how to use its API

Status: RESOLVED FIXED

(Testing :: Mozbase, defect)

Description

[William Lachance (:wlach)]

We currently have some command-line examples of how to use mozversion here:

http://mozbase.readthedocs.org/en/latest/mozversion.html#examples

Unfortunately these are only command line examples. It would be good to have a minimal example of how to use its API as well.

A minimal program using mozversion is quite simple:

  import mozversion

  version = mozversion.get_version(binary='/path/to/firefox-bin')
  for (key, value) in sorted(version.items()):
      if value:
          print '%s: %s' % (key, value)

It would be good to put something like this in the mozversion documentation under "API Usage". 

Steps to fixing this bug:

* Install and initialize a development version of mozbase per: https://wiki.mozilla.org/Auto-tools/Projects/MozBase#Installing_Mozbase_for_Development
* Edit the file testing/mozbase/docs/mozversion.rst to insert a code example like that above. You can see an example of the sphinx syntax to do that here: http://hg.mozilla.org/mozilla-central/file/a18ff2303b09/testing/mozbase/docs/mozdevice.rst#l30
* Generate the docs by going into 'testing/mozbase/docs' and running 'make html' and loading the output in `testing/mozbase/docs/_build/html/mozversion.html` in your web browser.
* Submit the patch per the instructions: https://wiki.mozilla.org/Auto-tools/Projects/MozBase#Working_on_Mozbase_and_Contributing_Patches

Comment 1

[Arnav Sharma]

Attachment: bug-1037532-fix.patch

Tried to follow the instructions provided. Thanks for the help :).

Comment 2

[William Lachance (:wlach)]

Comment on attachment 8454943 [details] [diff] [review]
bug-1037532-fix.patch

Review of attachment 8454943 [details] [diff] [review]:
-----------------------------------------------------------------

This looks good! I just realized that we may as well do up examples for Android and FirefoxOS while we're at it. Could you do a quick update of the patch for that?

Here's an example for Android:

Firefox for Android

version = mozversion.get_version(binary='/path/to/firefox.apk')
print version['application_changeset'] # gets hg revision of build

FirefoxOS

version = mozversion.get_version(sources='/path/to/sources.xml', dm_type='adb')
print version['gaia_changeset'] # gets gaia git revision

Comment 3

[anurag [anuragk]]

I would like to work on this issue, is this still open? 

This may sound little childish but I am bit lost, which channel on IRC can I contact you?

Comment 4

[Joel Maher ( :jmaher ) (UTC -8)]

Anurag, always feel free to ask questions!  wlach can be found in #ateam, feel free to ping me (jmaher) if you don't see him online.

Comment 5

[William Lachance (:wlach)]

(In reply to anurag from comment #3)
> I would like to work on this issue, is this still open? 
> 
> This may sound little childish but I am bit lost, which channel on IRC can I
> contact you?

Hi Anurag, this isn't a good issue to work on as Arnav's patch already does what we want. I'm sure we can find another issue for you to work on if you're interested though. :)

Comment 6

[William Lachance (:wlach)]

Hi Arnav, do you think you might have time to do the suggested improvement in comment 2? I'd love to get this pushed to the tree.

Comment 7

[Arnav Sharma]

Attachment: bug-1037532-fix.patch

added the changes outlined in comment 2.

Comment 8

[Arnav Sharma]

Attachment: bug-1037532-fix.patch

I should've ran `make html` /before/ uploading the patch. Forgot newlines. Whoops.

Comment 9

[William Lachance (:wlach)]

Comment on attachment 8457445 [details] [diff] [review]
bug-1037532-fix.patch

Excellent, thank you!

Comment 10

[William Lachance (:wlach)]

Suggested commit message:

"Bug 1037532 - Add API documentation for mozversion;r=wlach"

Author:  Arnav Sharma <[e-mail]>

Comment 11

[Arnav Sharma]

Comment on attachment 8457445 [details] [diff] [review]
bug-1037532-fix.patch

># HG changeset patch
># Parent 161fadfcbadc108d99fc23e36c30519a286d341c
># User Arnav Sharma <[e-mail]>
>Bug 1037532 - Add API documentation for mozversion;r=wlach
>
>diff --git a/testing/mozbase/docs/mozversion.rst b/testing/mozbase/docs/mozversion.rst
>--- a/testing/mozbase/docs/mozversion.rst
>+++ b/testing/mozbase/docs/mozversion.rst
>@@ -7,16 +7,37 @@ that it has been built from. This is com
> conditional logic based on the application under test.
> 
> API Usage
> ---------
> 
> .. automodule:: mozversion
>     :members: get_version
> 
>+Examples
>+````````
>+
>+Firefox::
>+
>+    import mozversion
>+
>+    version = mozversion.get_version(binary='/path/to/firefox-bin')
>+    for (key, value) in sorted(version.items()):
>+        if value:
>+            print '%s: %s' % (key, value)
>+
>+Firefox for Android::
>+
>+    version = mozversion.get_version(binary='path/to/firefox.apk')
>+    print version['application_changeset'] # gets hg revision of build
>+
>+FirefoxOS::
>+
>+    version = mozversion.get_version(sources='path/to/sources.xml', dm_type='adb')
>+    print version['gaia_changeset'] # gets gaia git revision
> 
> Command Line Usage
> ------------------
> 
> mozversion comes with a command line program, ``mozversion`` which may be used to
> get version information from an application.
> 
> Usage::

Comment 12

[Arnav Sharma]

(In reply to Arnav Sharma from comment #11)
> Comment on attachment 8457445 [details] [diff] [review]
> bug-1037532-fix.patch
> 
> ># HG changeset patch
> ># Parent 161fadfcbadc108d99fc23e36c30519a286d341c
> ># User Arnav Sharma <[e-mail]>
> >Bug 1037532 - Add API documentation for mozversion;r=wlach
> >
> >diff --git a/testing/mozbase/docs/mozversion.rst b/testing/mozbase/docs/mozversion.rst
> >--- a/testing/mozbase/docs/mozversion.rst
> >+++ b/testing/mozbase/docs/mozversion.rst
> >@@ -7,16 +7,37 @@ that it has been built from. This is com
> > conditional logic based on the application under test.
> > 
> > API Usage
> > ---------
> > 
> > .. automodule:: mozversion
> >     :members: get_version
> > 
> >+Examples
> >+````````
> >+
> >+Firefox::
> >+
> >+    import mozversion
> >+
> >+    version = mozversion.get_version(binary='/path/to/firefox-bin')
> >+    for (key, value) in sorted(version.items()):
> >+        if value:
> >+            print '%s: %s' % (key, value)
> >+
> >+Firefox for Android::
> >+
> >+    version = mozversion.get_version(binary='path/to/firefox.apk')
> >+    print version['application_changeset'] # gets hg revision of build
> >+
> >+FirefoxOS::
> >+
> >+    version = mozversion.get_version(sources='path/to/sources.xml', dm_type='adb')
> >+    print version['gaia_changeset'] # gets gaia git revision
> > 
> > Command Line Usage
> > ------------------
> > 
> > mozversion comes with a command line program, ``mozversion`` which may be used to
> > get version information from an application.
> > 
> > Usage::

Oh? That didn't do what I thought it would. Oops.

Comment 13

[Carsten Book [:Tomcat]]

https://hg.mozilla.org/integration/mozilla-inbound/rev/8f38755465a3

Comment 14

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/mozilla-central/rev/8f38755465a3