bugplucker.py
[-f forgetype
] [-i trackername:id
] [-u username
] [-p password
] [-r] [-v verbosity
] projecturl
The forgeplucker program does not yet exist. This placeholder page describes an ancestor, bugplucker.py, which is demonstration code expected to evolve into forgeplucker.
bugplucker.py can extract the complete state of a project's bug tracker from any supported hosting system. Uses for this capability including making emergency backups, working on buglists without network access, and statistical analyses of project histories.
For a list of supported systems, use the -?
option or -h
option.
The program requires one (projecturl) argument, a hosting-site name and project name separated by a slash ('/'). It produces a dump of the bugtracker state in JSON format on output. An alternative form for the 'projecturl' argument is in the form 'https://ADRESS/PROJECT_NAME'.
The program requires that you be a member of the project you are pulling state for, with the authority to modify tracker entries. This is not because the program modifies entries (it doesn't) but because its parsing techniques rely heavily on the structure of HTML 'select' elements in order to make sense out of what would otherwise be "text soup".
The program also requires that you have your user preferences on the site you are pulling from, set to display messages in English and display dates as local time for your timezone. Many hosting sites do not reliably display a timezone in dates, and timezone conversion is intrinsically unreliable where it is supported. Thus, the code must rely on localtime(3).
The program accepts the following options:
Specify the forge-system type. May not be necessary, as the program can infer a type from well-known hosting sitenames, if invoked with URL. A list of supported forges is provided with '-f help'
Set your username for authentication purposes (if none provided, then use LOGNAME env var's value)
Set your password for site-authentication purposes.
Fetch an individual detail page and return the JSON for the corresponding issue. The specification should be two colon-separated parts, a tracker name and a bug ID. Mainly useful for debgging.
Dump in XML format rather than JSON.
Set a numeric verbosity level, primarily for debugging. 1 enables various progress messages to standard error, and 2 enables dumping of web pages as they are fetched.
These options are mainly for testing purposes; for production it is recommended that you put your credentials in your .netrc file in order to avoid having to type your password frequently where it might be seen. The 'account' field, if present, will be interpreted as a forge type overriding the normal heuristics.
The program will change the settings on your tracker search form in order to collect all bugs. You will probably have to reset them afterwards.
It's not forgeplucker yet. Forgeplucker will capture the project's entire state, not just the trackers.
Bugplucker dumps are all in JSON, but the shape and keywords are forge-type-specific. At a later stage of the project, once we have gained field experience with many hosting sites, we expect to design a uniform dump file format.
No tools yet exist to import the dumps into forge systems. They cannot be written until we have a standardized format.
The range of supported systems could be larger, and will be.