mozversion should have documentation on how to use its API

RESOLVED FIXED in mozilla33

Status

defect
RESOLVED FIXED
5 years ago
5 years ago

People

(Reporter: wlach, Assigned: arnav.pokemonfan, Mentored)

Tracking

Trunk
mozilla33
x86_64
Linux
Points:
---

Firefox Tracking Flags

(Not tracked)

Details

(Whiteboard: [good first bug][lang=python])

Attachments

(1 attachment, 2 obsolete attachments)

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
Posted patch bug-1037532-fix.patch (obsolete) — Splinter Review
Tried to follow the instructions provided. Thanks for the help :).
Attachment #8454943 - Flags: review?(wlachance)
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
Attachment #8454943 - Flags: review?(wlachance) → feedback+
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?
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.
(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. :)
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.
Flags: needinfo?(arnav.pokemonfan)
Posted patch bug-1037532-fix.patch (obsolete) — Splinter Review
added the changes outlined in comment 2.
Attachment #8454943 - Attachment is obsolete: true
Attachment #8457442 - Flags: review?(wlachance)
Flags: needinfo?(arnav.pokemonfan)
I should've ran `make html` /before/ uploading the patch. Forgot newlines. Whoops.
Attachment #8457442 - Attachment is obsolete: true
Attachment #8457442 - Flags: review?(wlachance)
Attachment #8457445 - Flags: review?(wlachance)
Comment on attachment 8457445 [details] [diff] [review]
bug-1037532-fix.patch

Excellent, thank you!
Attachment #8457445 - Flags: review?(wlachance) → review+
Suggested commit message:

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

Author:  Arnav Sharma <arnav.pokemonfan@gmail.com>
Keywords: checkin-needed
Assignee: nobody → arnav.pokemonfan
Comment on attachment 8457445 [details] [diff] [review]
bug-1037532-fix.patch

># HG changeset patch
># Parent 161fadfcbadc108d99fc23e36c30519a286d341c
># User Arnav Sharma <arnav.pokemonfan@gmail.com>
>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::
(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 <arnav.pokemonfan@gmail.com>
> >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.
https://hg.mozilla.org/mozilla-central/rev/8f38755465a3
Status: NEW → RESOLVED
Closed: 5 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla33
You need to log in before you can comment on or make changes to this bug.