If you think a bug might affect users in the 57 release, please set the correct tracking and status flags for Release Management.

Manifestparser documentation should be reworked

NEW
Unassigned

Status

Testing
Mozbase
3 years ago
3 years ago

People

(Reporter: wlach, Unassigned)

Tracking

Trunk
x86_64
Linux
Points:
---

Firefox Tracking Flags

(Not tracked)

Details

We talked about this in some point in the past, but never took any action on it. 

The ManifestParser documentation leaves a bit to be desired in its current state. It has way too much material talking about design decisions and implementation details, and way too little information on how to use this module for your project.

I'd like to rework what we have here (http://mozbase.readthedocs.org/en/latest/manifestdestiny.html) with the following:

1. A very succinct description of how you can use manifestdestiny to track test information across a set of directories, along with a toy example of how this might work.
2. A quick tour of some other use cases provided by manifestparser (e.g. the disabled stuff, the ability to run some tests per platform) along with concrete examples of how to do these things (instead of just talking about them in the abstract).

I would like to kill the following sections:

1. The discussion of manifestdestiny architecture.
2. The tests, bugs, design considerations, historical reference sections. 

Most of these are out of date and none are really relevant for most people.

I am uncertain about the discussion of the manifestparser command line client. Are we still actively using that in some way? Even if we are, is it something we really want to document in the manifestdestiny documentation? It kind of seems more useful for converting over existing tests to manifest format, which AFAIK is now done?

In general I'd like to just focus on providing the minimum required to get people up and running with this thing. If people really want to know the details they can dig into the source, do a google search, or ask questions on #ateam.
This all sounds great. I'd ditch the command line client stuff, I've never had reason to use it and can't imagine anyone else has. Ideally we'd have a very simple example like:
1) Write a simple manifest like so
2) Write this code snippet to read it
3) Do something with the list of tests

...and then a bit of expounding on the other features of manifests.

I'm not sure if it's useful, but we have some related documentation here mostly focused on the specific use of test manifests with our test harnesses:
https://ci.mozilla.org/job/mozilla-central-docs/Tree_Documentation/buildsystem/test_manifests.html#manifestparser-manifests
You need to log in before you can comment on or make changes to this bug.