https://github.com/bugzilla/bugzilla-schema

A tool to generate documentation of the differences between Bugzilla schema versions
https://github.com/bugzilla/bugzilla-schema

Last synced: about 1 month ago
JSON representation

A tool to generate documentation of the differences between Bugzilla schema versions

• Host: GitHub
• URL: https://github.com/bugzilla/bugzilla-schema
• Owner: bugzilla
• Created: 2024-04-28T08:32:47.000Z (8 months ago)
• Default Branch: main
• Last Pushed: 2024-05-04T10:04:42.000Z (8 months ago)
• Last Synced: 2024-05-04T23:20:39.542Z (8 months ago)
• Language: Roff
• Homepage: https://schema.bugzilla.org
• Size: 1.12 MB
• Stars: 0
• Watchers: 0
• Forks: 7
• Open Issues: 0
• Metadata Files:
  • Readme: readme.rst

Awesome Lists containing this project

README

        
Bugzilla Schema Doc Generation

==============================

1. Introduction

---------------

This repository contains the code and documents used to generate

the `online Bugzilla schema documentation `_,

produced as a side-benefit

of the `Perforce Defect Tracking Integration `_ project.

2. Index

--------

================== ====================================================================

File               Description

================== ====================================================================

pickle_schema.py   A Python module to interrogate MySQL to obtain a live database

                   schema, and to write a "pickled" version of that schema into a file

                   in the "pickles" directory.

pickles            A directory containing pickled versions of every Bugzilla

                   database schema, generated by pickle_schema.py.  Each pickle is

                   named after the first version of Bugzilla which had that

                   schema.

get_schema.py      A Python module to read a pickled schema from the "pickles"

                   directory, annotate it with data from schema_remarks.py, and convert

                   it to a canonical Python dictionary form.

schema_remarks.py  A Python module defining all the comments and running text which

                   are ever used in the generated documentation (excluding

                   automatically-generated text such as field names, types, attributes,

                   and notes on schema changes).  Also lists the schemas available in

                   "pickles", and provides the mapping from Bugzilla version to schema

                   version name.

make_schema_doc.py The main Python documentation generation module.  Uses the

                   unpickled schemas fetched by get_schema.py, compares them to

                   identify schema changes and colour the resulting charts, processes

                   the text to include comments appropriate to the range of schemas

                   requested, and automated comments reflecting the schema version

                   ranges specific to particular pieces of commentary, and produces the

                   resulting HTML document.

index.py           The front-end CGI script which presents a form, validates input

                   through the form, and drives make_schema_doc to produce the schema

                   documentation.

index.cgi          A tiny Python script which uses index.py to do all of the CGI

                   work.  The two files are separated so that the source of index.py

                   can be published directly through the same web interface as the

                   generated schemas.

================== ====================================================================

3. Requirements

---------------

For hosting:

- Python

- a web server that can run Python CGI.

For updating:

- The above, and also:

- The ability to create Bugzilla installations for different versions of Bugzilla,

  using MySQL.

- MySQLdb.

- Understanding of Perl, and of Bugzilla internals.

- Patience.

For guidance on updating the tool to handle newer Bugzilla releases, see `updating.rst`_.