codelist-genericode: An XSLT repository from OASIS GitHub Repositories for TC Work

Members of the OASIS Code List Representation TC create and manage technical content in this TC GitHub repository (https://github.com/oasis-tcs/codelist-genericode/) as part of the TC's chartered work (the program of work and deliverables described in its charter).

OASIS TC GitHub repositories, as described in GitHub Repositories for OASIS TC Members' Chartered Work, are governed by the OASIS TC Process, IPR Policy, and other policies. While they make use of public GitHub repositories, these repositories are distinct from OASIS Open Repositories, which are used for development of open source licensed content.

Description

The OASIS genericode specification incorporates documentation and a number of supporting machine-readable artefacts for the representation and IT-enablement of coded domains populated by "a set of codes representing X". Per the ISO/IEC 14662 Open-edi Reference Model this will satisfy an implementation of the Functional Services View of code lists where the Business Operational View is documented in ISO/IEC 15944-10 IT-enabled coded domains as semantic components in business transactions.

The documentation is authored in XML and published in two layouts: the OASIS specification layout and the ISO/IEC Directives Part 2 layout (the latter for potential PAS submission to JTC 1 for international standardization).

Various artefacts, existing and identified to be developed, will be incorporated into the repository for inclusion in the final deliverable.

Branches, roles, and protocol for contributions

Two branches are restricted (by policy, not by software so please be careful):

main - this is content that has been reviewed by committee members and considered acceptable to be distributed for its intended purpose (which may be for testing or for production use, not necessarily for final use)
review - this is content from the editor that has not been reviewed by committee members yet, and so is not considered agreed-upon for its intended purpose, but the editor has incorporated input from other sources into a package for review; when there is consensus about the content of the review branch, it is snapshot in the main branch

A "main" copy is not necessarily the final copy, but simply a copy of a "review" copy whose review has been completed.

Two roles are identified.

Editors are responsible for incorporating into review copies (for committee consideration) and main copies (already accepted by the committee) the suggestions made by the maintainers.

Maintainers create and maintain their own branches and are asked not to check in any changes to the main and review branches reserved for editors.

Contributions are requested to be submitted by pull requests against the review branch to be incorporated by the editor. Maintainers can create and delete any number of their own branches as they see fit. Maintainers are reminded to pull the review changes frequently so as not to diverge far from the work currently under review.

Maintainers can use any XML editing tool to make their changes to the specification document. See "Preview results" below regarding how they can preview their XML edits locally.

Other files and directories can change however needed by the maintainer.

The act of checking a committed branch to GitHub automatically triggers the publishing of the authored XML into OASIS layout PDF, OASIS layout HTML, and ISO Directives Part 2 layout PDF. See "Published results" below.

Detailed steps

The maintainer creates their own personal other branch of their own naming, not overlapping with the name used by any other maintainer or editor, and always pulls from the review branch into it. Pulling from the review branch must be done after every time the editor updates the review branch.
The maintainer makes the changes they wish to their local copy of the other branch. A local preview facility allows the maintainer to preview in a web browser their edits to the specification fully formatted as an OASIS specification. When completed they commit their changes and push their changes to GitHub in their private branch.
Every push to GitHub triggers a GitHub Action that forwards a copy of the XML to the https://www.RealtaOnline.com API entry point specific to the desired outputs.
Réalta prepares the HTML and PDF outputs for the OASIS layout and the PDF output for the ISO Directives Part 2 layout.
Réalta returns to GitHub the published results in a ZIP file. The Action’s script unzips the results and packages them in a doubly-zipped ZIP file. The outer ZIP is used to wrap the Action’s artifacts results. The inner two ZIP files wrap for posting to the OASIS Kavi server, respectively, the work product inputs and intermediate files for archive purposes, and the set of work product files to be posted by TC Administration to the OASIS Docs server. These Action results are transient and not placed into the GitHub code repository. Eventually GitHub deletes old Action results. The maintainer downloads the GitHub Action’s artifacts ZIP file for their review and, if desired, local backup. If they wish to make changes, they return to step 2 and repeat the process.
When the maintainer is satisfied with their work to be reviewed by the editor and other team members, they send a pull request to the editor describing their changes that they have committed to their other branch.
The editor reviews the pull request and, if satisfied with the contribution, they pull the server’s copy of the other branch into their local environment and merge it into the review branch. The editor can continue to make any changes they wish in their local copy of the review branch.
When the editor has incorporated changes from all of the contributing maintainers and is prepared to make the review document available, they push their review branch to GitHub. This push automatically triggers the GitHub Action running the complete publishing process that returns the work product ready for the editor to download from GitHub to review. The GitHub Action results are posted to Kavi for the committee and public to download the published results and review. The artifacts ZIP is manually unpacked revealing the two inner ZIPs that are then uploaded to the OASIS Kavi server for posterity and to fulfill the obligation to the public that intermediate work products be easily available. Following the OASIS TC Process the committee can qualify a snapshot on the OASIS Kavi server to be uploaded by OASIS TC Administration to the OASIS Docs server. If maintainers wish to make changes they return to step 1 (not step 2) and repeat the process.
When the editor has accommodated all of the feedback from committee members regarding the review and wishes to archive a snapshot for public use, they merge their local review branch into their local main branch.
The editor pushes their local main branch to GitHub. While this push will produce a set of artefacts, those artefacts are ignored and deleted by the editor because they may have different timestamps than the files approved by committee and uploaded to Kavi. But anyone wanting a snapshot of the source material (modulo remotely changed files such as spreadsheets) can find the last approved set from the main branch.

Repository contents

Directories:

.github/workflows - the automated publishing and packaging process triggers performed for every push
cs01 - the results of publication of the Committee Specification 01 dated 28 December 2007
doc - documentation inputs
- doc/genericode.xml - the specification file being edited
- doc/art/*.png - PDF artwork (maximum width 5.5"/140mm, minimum resolution 300dpi/11.8dpmm)
- doc/htmlart/*.png - HTML artwork (maximum width 750px, resolution irrelevant but one could use 72dpi or 96dpi)
- doc/db - OASIS DocBook library required for HTML presentation and XML presentation
oXygen-frameworks - document-authoring support for the oXygen XML tool (see the directory README file)
sch - Schematron value constraints
utilities/ant - publishing process support
xsd - W3C XML Schema structural constraints

Support files:

produceGenericode.* - GitHub action publishing and packaging process files converting XML to end-user PDF and HTML documents
realta* - publishing process support files

Authoring and generated content

Two conformance clauses collect the auxiliary rules of genericode into summaries. To relieve the author of the burden of maintaining consistency between the rules authored in the body and the rules summarized for conformance, the publishing process on GitHub synthesizes the conformance clauses by harvesting the rules from the authored content.

When the repository is pushed to GitHub, the authored genericode.xml XML and two stub entity XML files are uploaded. The stub entity files are not to be modified in any way by authors.
The three files are input into the rules2entities.xsl stylesheet in order to generate the entity files composing the conformance clause content by harvesting those tables marked with role="rule" in DocBook
The assembleEntities.xsl stylesheet creates the monolithic output genericode-{version}-{stage}.xml preserving the document type declaration and incorporating the generated entities
The monolithic file is used for publishing and for distribution to users in the finalized work products

Preview results

Intermediate edits saved to the local doc/genercode.xml file can be previewed instantly in a browser on your computer. It is recommended that one do this to establish their edits are satisfactory before checking in to GitHub to trigger the published results.

Note that the preview HTML presents the high-resolution PDF images, not the low-resolution HTML images and so the images are dramatically oversized in the browser window. This is not the case for the published HTML returned from GitHub.

Once the XML has been opened in the browser, it is necessary only to refresh the browser window after each save of the XML edits. It is not necessary to go through again the drag-and-drop or open requests.

Opening the XML in Windows:

drag and drop the XML source onto Internet Explorer, or "right-click, Open with..., Internet Explorer"
use Ctrl-R or F5 to refresh the browser after editing the file
this does not work with Firefox, Chrome, or Edge browsers

Opening the XML in Mac OSX:

drag and drop the XML source onto Safari, or "right-click, Open With, Safari"
use Cmd-R to refresh the browser after editing the file
this does not work with Firefox or Chrome browsers

The auxiliary rules conformance clauses in the preview are the entity stubs not to be changed by the author. The publishing process will create the distributed XML that includes the populated conformance clauses.

Published results

The published results are not stored in the GitHub repository, per se.

See the Actions tab for the results of publishing processes and distribution packaging, being careful to note the branch indicated for the desired commit message. As branches are merged the commit message is inherited in the merged branch.

You must be signed in to GitHub in order to download the results from the "Artifacts" section on the action's build result page. If not, you will get a "404 Not Found" error for the build result page.

Each downloaded result is doubly-zipped: the outer zip for GitHub extraction purposes and the inner zips for posting to Kavi and distribution.

These files are made publicly available in the committee Kavi documentation (members only) (Public access) repositories. The results should then be deleted from the Actions tab to save space.

The results in the Actions tab eventually are deleted automatically by GitHub, but if you have no need for a particular build result, you can delete it to save space. Please keep this in mind if you are using the GitHub web interface and creating results for every commit of every file.

Contributions

As stated in this repository's CONTRIBUTING file, contributors to this repository must be Members of the OASIS Code List Representation TC for any substantive contributions or change requests. Anyone wishing to contribute to this GitHub project and participate in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the OASIS Feedback License.

Licensing

Please see the LICENSE file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the Code List Representation TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository LICENSE.

Contact

Please send questions or comments about OASIS TC GitHub repositories to the OASIS TC Administrator. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the Code List Representation TC's home page.