The reference list
The standards, specifications and papers that QC Items cite are kept in one managed list: Managed data > References in the menu. An Item can pick a reference from the list instead of typing it. This keeps the spelling, the links and the editions of a specification in one place, and tells us which Items to look at when a specification changes.
Who can do what
| Public | Editor | Workflow manager | |
|---|---|---|---|
| See the list | the references used by published or withdrawn Items | all references | all references |
| Add a new reference | no | yes (added as unofficial) | yes (can tick Official) |
| Change a reference on an Item | no | yes (saved as a new unofficial version) | yes (can tick Official) |
| Edit an entry on the reference list | no | no | yes (a new version) |
| Set or remove Official | no | no | yes |
| Sources and scan | no | no | yes |
An entry that any Item uses cannot be deleted.
What an entry holds
The entry form has a frame called Used in current data model. It holds the three fields an Item publishes, each with the name it has in the data model in brackets:
- Short Title (Text): the name Items cite, for example
ITU-R BT.709-6. Required. - URLs (URI): where to get the spec; the first is the default.
- Remarks (Remark).
Below the frame are the other fields:
- Organisation (for example SMPTE): required.
- Full Title: the full title as used in the specification itself.
- Unique ID (optional, recommended): identifies the spec itself, for example its URL. See The Unique ID below.
- Spec version and Spec date.
Required fields apply to every new entry. The Spec date may be a year (2020), a month (2020-04) or a day (2020-04-30), as many specifications only give a year.
The API is not affected: an Item still publishes the reference as a Name (the Short Title), a URI (the first URL) and a Remark. Full Title, Organisation, Spec version and Spec date are for the list only.
Versions: our entry and the specification
Two different things can change, and they are kept apart:
- Our entry changes (a typo, a broken link). This is a new version of the entry. Each version records the date, who made it and an optional note such as "typo corrected".
- The specification changes (a new edition). This is a new entry with the new Spec version and Spec date, and the same Unique ID as the old edition.
The Unique ID
The Unique ID identifies the spec itself, not one edition of it: the URL of the spec is a good choice. All the editions of a spec (BS.1770-3, BS.1770-4, ...) are separate entries that carry the same Unique ID, and that is how the list knows which entries belong together and which one is the latest.
- It is optional, and many entries start without one (a new unofficial entry often has none). Editions of a spec only group once they all have it, so fill it in when you add an edition.
- It can be set while it is empty. Once it is set, only a workflow manager can change it, because every edition has to change with it: the new value is then written to every entry and every version that had the old one, so the editions stay together. It cannot be removed.
- Two entries with the same Unique ID (ignoring upper and lower case) belong to the same spec.
- An edition needs a Spec date or a Spec version so the editions can be put in order. Give every edition of a spec a date, or every edition a version; an entry with a date always counts as newer than one without.
Picking a reference in an Item
In the Item edit page, the References card has a search box above the rows. Type part of a title or organisation, and pick the entry. The row is filled from the list and is read only. Under the row you also see the entry's Organisation, Full Title, Spec version and Spec date, which are not published with the Item but help you check that you picked the right one. To add an entry that is not in the list, use add it to the list: the form there has all fields.
Each row also has a Version choice. It says which version of the specification the row means:
- This version: the row stays on that spec version (for example BS.1770-3) and never moves to another spec version by itself. It does follow the entry: when a workflow manager makes a corrected or newer official version of the same entry, the Item check says so and saving the Item takes it over. The search offers it when the entry has a spec date or a spec version.
- Latest version: the row means the newest official entry with the same Unique ID, ordered by spec date and then spec version. When a newer version appears, the Item check says so ("A newer version of the reference ... is in the list"), and saving the Item takes it over. The search offers it when the entry has neither a date nor a version, as a reference without a date means the latest version.
Whatever the version, a row always uses the current wording of its entry. When a workflow manager corrects the entry, the Item check says so ("The reference ... was corrected in the list"), and saving the Item takes the corrected wording over. Making an entry official is not a correction. A published Item never changes by itself.
You can still see references that were typed by hand before the reference list existed. They are called free text. Free text works as before, but the check References are picked from the reference list shows a yellow finding, so replace it by an entry of the list when there is one. The finding can be confirmed and never stops publication.
Official and unofficial
A new entry is unofficial until a workflow manager makes it official. A workflow manager can also tick Official when adding the entry.
- Every entry has versions. The version that counts, the current version, is the newest official one. Unofficial versions that editors add on top do not change it, so other editors and the public do not see them.
- An Item that uses an unofficial reference, or an unofficial version, shows a yellow warning (the check References are official). It does not stop the Item from moving to any status, and you can confirm it.
- A reference that is used by a published or withdrawn Item cannot lose its official flag.
Adding and changing a reference on an Item (editors)
The References card of an Item has two buttons.
New adds an empty reference. Fill in every field you know (Short Title and Organisation are required). When you save the Item, the reference is added to the reference list as unofficial, and the Item cites it. A workflow manager decides on it later.
From reference list opens a search. Type part of the title, the organisation or the ID. Only official references are listed. Choose a spec; if it has several spec versions (the version and date of the specification itself, for example BS.1770-3 and BS.1770-4), choose the Latest spec version or one specific spec version. The fields are shown but locked.
To change something, choose Edit. The fields become editable and Official is switched off. When you save the Item, your change is added as a new unofficial version of the same reference. The Item cites that version. Nobody else is affected: the reference list and the other Items keep showing the official version until a workflow manager makes your version official, or combines it with others into a new official one.
Workflow managers see Official as a tick box and can tick it when they add or change a reference. It is not ticked by default, so they behave like editors unless they tick it.
Handling versions (workflow managers)
When editors change a reference on an Item, their change is a new unofficial version. Open the entry and choose Manage versions (the number on the button is how many versions wait for a decision).
The page lists all versions, newest first, with who made each one, the date, the note, how many Items cite it and its state. A row has a colour:
- yellow: waits for a decision;
- light green: handled, and official;
- light red: handled, and unofficial;
- grey: split off, merged or combined into another version.
Each row has four buttons. Whichever you use, the row counts as handled and leaves the to-do list:
- Make official / Make unofficial: sets the flag. The current version of the entry is its newest official version.
- Split off: the version moves to a reference of its own, with a new Unique ID (you can type your own). Use it when the editor's change is really another spec, not a version of this one.
- Merge onto: the version moves on top of another reference that you search by title, organisation or Unique ID, and takes its Unique ID.
Versions are never changed or deleted, apart from the flag, the handled mark and the Unique ID. A version that moves keeps its content; the Items that cite it keep citing it.
Compare two versions. Tick two versions in the table to see them side by side, field by field, with the changed words marked.
Combine into a new version. Under the table, each field shows what the waiting versions propose compared with the current version. The value used by the most Items comes first (marked with a star); for URLs there is also an option that takes all of them. Click a value to put it in the new version, edit the rest by hand and choose Save as new version. The new version is official unless you untick Official, and the waiting versions are marked as handled (combined).
Sources and the weekly scan (workflow managers)
Managed data > References > Sources lists the organisations whose publications are scanned. Each source has a switch to include it in the weekly scan, the rule that says what is scanned, and the result of the last scan. A new source is added by a workflow manager; the first ones come from the organisations already cited by Items.
Scan all active sources now starts a scan without waiting for the weekly one (Mondays). A scan does two things for every source:
- It checks the URLs of the entries of that organisation that Items use, one after the other with a short pause. Entries that a scan added and that no Item uses yet are not checked. A URL that does not work, or that has moved, appears under Findings.
- It reads the organisation's own publication list, when the organisation has a scan rule, and adds the documents that are not in the list yet. They are added as unofficial entries, with the note "Added by the scan of ...", and a workflow manager makes them official when they are checked.
Every organisation publishes its documents differently, so each one has its own rule. Organisations without a rule only get the URL check; the Sources page shows which rule a source has.
| Organisation | What is scanned |
|---|---|
| SMPTE | The list of documents at pub.smpte.org/doc (ST, RP, EG, RDD and OV). The page has no dates, so it is read in full each time and only new documents are added. |
For lists that show dates, the scan reads the newest documents first and stops when it reaches documents older than the newest one of the previous scan. The first scan is therefore the longest.
Findings
Under Findings, a workflow manager decides on what needs a person:
- a moved URL: Create a version with the new URL (added as a new, unofficial version of the entry, which is then handled like any other version), or dismiss;
- a URL that does not work: Edit entry to fix the address, then dismiss the finding;
- a related spec found by the scan: Add to the reference list (added as an unofficial entry), or dismiss.