Members of the OASIS Universal Business Language (UBL) TC create and manage technical content in this TC GitHub repository ( https://github.com/oasis-tcs/ubl ) as part of the TC's chartered work (i.e., 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, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from OASIS TC Open Repositories, which are used for development of open source licensed content.
Description - the purpose of this repository
Published results - finding the official published results (hint: not in GitHub!)
Branches, roles, and protocol for contributions - where, who, how: overview
Detailed steps - where, who, how: detail
Creating a new release - getting started
Setup for technical committee work products - for editors
Setup for subcommittee work products - for subcommittee chairs
Setup for other maintainer - for other maintainers
Configuring the artefacts - preparing artefacts
Configuring the hub document - preparing documentation
Preview results - reviewing documentation
Producing new results - working day-to-day
Reproducing old results - late recovery when needed
Results - what to look for after you have committed/pushed
Housekeeping - important cleanup
To do: - shouldn't be long
The purpose of this repository is to support committee-member collaborative activity in developing releases of the UBL committee's flagship work product, the UBL OASIS Standard. The initial Maintainer is G. Ken Holman (GitHub: gkholman) of Crane Softwrights Ltd.. Until further notice, questions regarding this repository may be directed to Ken.
The Universal Business Language (UBL) is an open library of standard electronic XML business documents for procurement and transportation such as purchase orders, invoices, transport logistics and waybills.
UBL defines "a generic XML interchange format for business documents that can be restricted or extended to meet the requirements of particular industries. Specifically, UBL provides the following:
- A suite of structured business objects and their associated semantics expressed as reusable data components and common business documents
- A library of XML schemas for reusable data components such as "Address", "Item", and "Payment" — the common data elements of everyday business documents
- A set of XML schemas for common business documents such as "Order", "Despatch Advice", and "Invoice" that are constructed from the UBL library components and can be used in generic procurement and transportation contexts..."
The published results are not stored in the GitHub repository, per se.
See the GitHub 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 archived by editors and subcommittee chairs, as needed, 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 after 90 days, 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.
Three branches are restricted (by policy, not all by software so please be careful):
main- this is content that has been reviewed by committee members and considered acceptable to be backed up on Kavi and, if necessary, 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 thereviewbranch, it is snapshot in themainbranchubl-version-stage- (e.g.ubl-2.3-csd05) this is content the editor is working on while thereviewbranch is being reviewed by committee members; this is not to be considered final and may be in a state of disrepair while it is being worked on; when the editor is ready for the committee to review it, it will be checked into the review 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,review, orubl-version-stagebranches reserved for editors.
Maintainers can create and delete any number of their own branches as they see fit. Maintainers are reminded to pull the active review changes frequently so as not to diverge far from the work already progressed by the editor. Contributions are requested to be submitted by pull requests against the current review branch to be incorporated by the editor.
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.
Become a maintainer by sending your GitHub account name and associated email address to the committee chair(s) requesting that OASIS TC Admin grant you the required privileges in the repository.
This details the relationship between the main, review, and all other branches, and the roles responsible for them.
Maintainers focus on steps 1, 2, 5, and 6. Editors focus on steps 7, 8, 9, and 10. Steps 3 and 4 are automated by GitHub Actions.
- The maintainer creates their own personal
otherbranch of their own naming, not overlapping with the name used by any other maintainer or editor, and always pulls from thereviewbranch into it. Pulling from thereviewbranch must be done after every time the editor updates thereviewbranch. - The maintainer makes the changes they wish to their local copy of the
otherbranch. 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 and DOCX outputs for the ISO Directives Part 2 layout. The OASIS outputs are included in the distribution ZIP. The ISO outputs are included in a dedicated ZIP.
- 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 for download from GitHub. The inner three ZIP files for posting to the OASIS Kavi server are, respectively, the work product inputs and intermediate files for archive purposes, the ISO publishing outputs, and the set of distribution 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, but participants are encouraged to delete the workflows and files as soon as possible. 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
otherbranch. - The editor reviews the pull request and, if satisfied with the contribution, they pull the server’s copy of the
otherbranch into their local environment and merge it into their localUBL-{version}-{stage}branch or directly into their localreviewbranch. Typically the editor will continue to make any changes they wish in their localUBL-{version}-{stage}branch, pushing their intermediate work to review their progress. - When the editor has incorporated changes from all of the contributing maintainers and is prepared to make the review document available, they merge their local
UBL-{version}-{stage}branch into their localreviewbranch and push theirreviewbranch 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 three 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
reviewbranch into their localmainbranch. - The editor pushes their local
mainbranch 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 themainbranch.
If you are changing the Google spreadsheet but not any of your repository files, you cannot do a git push until you create a temporary file in your directory and then push the temporary file to the repository. The next time around, you can delete the temporary file in your directory and then push the deletion to the repository. Either of these steps will trigger GitHub actions that will reach out to the Google spreadsheet and run the process.
Two examples of the use of temporary files in a shell script are:
touch trigger.txt- creates the temporary filerm trigger.txt- deletes the temporary file
Two examples of the use of temporary files in a DOS script are:
echo >trigger.txt- creates the temporary filedel trigger.txt- deletes the temporary file
The build.sh invocation points to the particular set of parameters to use to create the artefacts. The editors maintain this file for the technical committee version of the UBL package. Alternative configurations for subcommittees can be created in subcommittee branches of this repository. As is true for other maintainers, subcommittee changes are submitted as a pull request to review. The subcommittee's build.sh is not used by the technical committee.
Whether you are creating a new committee version (e.g. UBL-2.4) or a new subcommittee version (e.g. UBL-2.4-TSC) you will need to create new document model spreadsheets: e.g. UBL-2.4 from final UBL-2.3, and UBL-2.4-TSC from current UBL-2.4. The document models are downloaded directly from Google during the GitHub Action. Each document is referenced in the invocation script as follows:
libGoogle=https://docs.google.com/spreadsheets/d/1bWAhvsb8..library.spreadsheet..iCMLhgUrHFzY
- the URL of your Google spreadsheet for the common library (be sure not to include the "
/edit..." at the end of the browser bar)
docGoogle=https://docs.google.com/spreadsheets/d/1P-3yEI0..documents.spreadsheet..0NTmINxksPQ
- the URL of your Google spreadsheet for the documents (be sure not to include the "
/edit..." at the end of the browser bar)
sigGoogle=https://docs.google.com/spreadsheets/d/1bWAhvsb8..signature.spreadsheet..hgUrHoiCML
- the URL of your Google spreadsheet for the common library (be sure not to include the "
/edit..." at the end of the browser bar)
Starting work on a new stage or a new version involves creating a new branch off of the stage or version last developed. Once the branch is created, first modify build.sh as required.
Consider this example of UBL 2.3 CSD05 that follows stage UBL 2.3 CS01 and version UBL 2.2:
export title="UBL 2.3"
export package=UBL-2.3
export UBLversion=2.3
export UBLstage=csd05
export UBLprevStageVersion=2.3
export UBLprevStage=cs01
export UBLprevVersion=2.2
export rawdir=raw
export includeISO=false
export libGoogle=https://docs.google.com/spreadsheets/d/1bWAhvsb8..library.spreadsheet..iCMLhgUrHFzY
export docGoogle=https://docs.google.com/spreadsheets/d/1P-3yEI0..documents.spreadsheet..0NTmINxksPQ
export sigGoogle=https://docs.google.com/spreadsheets/d/1bWAhvsb8..signature.spreadsheet..hgUrHoiCML
Before the process runs, the spreadsheets on Google should reflect the new stage string in the spreadsheet name. Examples:
- UBL 2.3 Library Elements Spreadsheet - CS01 master
- UBL 2.3 Document Elements Spreadsheet - CS01 master
The genericode file of the UBL vocabulary of the previously-published stage must replace that of the previous previously-published stage.
- e.g. for UBL 2.3 the
UBL-Entities-2.2.gcandUBL-Signature-Entities-2.2.gcfiles from the UBL 2.2 release must exist in the directory
The genericode file of the UBL vocabulary of the previously-published stage must replace that of the previous previously-published stage.
- e.g. if the stage previous to
csd05wascs01, then forcs02replaceUBL-Entities-2.3-cs01.gcwithUBL-Entities-2.3-csd05.gc(the renamedUBL-Entities-2.3.gcfile from thecsd05release) - do the same for the
UBL-Signature-Entities-*.gcfiles
When creating a branch reserved for your subcommittee, you will be responsible for tailoring the configuration to be distinct from the technical committee work products with your own spreadsheets.
Consider an example for the Transportation Subcommittee might be along the lines of a proposed UBL 2.3 TSC CSD03 that follows stage UBL 2.3 CSD02 and version UBL 2.2.
If you are proposing spreadsheet changes, you will need to copy the CSD02 technical committee spreadsheets into separate subcommittee spreadsheets and change the titles of the spreadsheets accordingly.
First create a new branch off of the stage or version last developed. Once the branch is created, the second step is to modify build.sh as required (note how the title and package have been customized with the subcommittee abbreviation):
export title="UBL 2.3 TSC"
export package=UBL-2.3-TSC
export UBLversion=2.3
export UBLstage=csd03
export UBLprevStageVersion=2.3
export UBLprevStage=csd02
export UBLprevVersion=2.2
export rawdir=raw
export includeISO=false
export libGoogle=https://docs.google.com/spreadsheets/d/OKIu..library.spreadsheet..Cpp5O
export docGoogle=https://docs.google.com/spreadsheets/d/iJ5D..documents.spreadsheet..5h1tA
export sigGoogle=https://docs.google.com/spreadsheets/d/4mc6..signature.spreadsheet..OXE5T
Before the process runs, the spreadsheets on Google should reflect the new committee acronym in the spreadsheet name. Examples:
- UBL 2.3 TSC Library Elements Spreadsheet
- UBL 2.3 TSC Document Elements Spreadsheet
The other non-documentation artefacts configured by the technical committee should be sufficient to re-use as they are.
If you are not working on the spreadsheets, it should be enough simply to create a new branch of your own from either the technical committee branch or one of the subcommittee branches, and re-use the configuration files as given.
However, if you have to modify the spreadsheets, you could choose to operate as if you were a one-person subcommittee and follow all of the subcommittee directions for configuration.
In fact, you could choose always to operate as if you are a one-person subcommittee and make configuration file changes to distinguish your work products from those of other maintainers. But this is not an obligation if all you have to do is submit revised text.
Each revision is described by the following configuration files for the artefacts:
- target identification when converting ODS to genericode
- XSD and JSON schema configuration
config-UBL.xml- IMPORTANT NOTE 1: there is version information in a comment at the top of this configuration file that, when the version or the stage changes, must be manually added to comments in the eight
UBL-*.xsdXSD schema fragments found in the directoryraw/xsd/commonLibrary: OASIS Universal Business Language (UBL) 2.x *STAGE-UPPER-CASE*http://docs.oasis-open.org/ubl/*stage-lower-case*-UBL-2.x/Release Date: *DATE*
- IMPORTANT NOTE 2: the same eight
UBL-*.xsdXSD schema fragments found in the directoryraw/xsd/commonhave explicitversion=and schema references assuming the current UBL version; these need to be updated when creating a new version release but not when creating a new stage release - IMPORTANT NOTE 3: the
UBL-*.jsonJSON schema extension components fragment found in the directoryraw/json-schema/commonhas explicit schema references assuming the current UBL version; these need to be updated when creating a new version release but not when creating a new stage release
- IMPORTANT NOTE 1: there is version information in a comment at the top of this configuration file that, when the version or the stage changes, must be manually added to comments in the eight
config-UBL-Signature.xml- IMPORTANT NOTE: this file has the same version information as found in
config-UBL.xmlthat needs to be updated as required
- IMPORTANT NOTE: this file has the same version information as found in
- Google bug-avoidance model name massage directives
- CVA master file for code list second-pass validation
- Schematron pattern for UBL's document constraints
UBL-DocumentConstraints-{UBLversion}.sch
- shell wrapper for generated CVA Schematron pattern
UBL-DefaultDTQ-{UBLversion}.sch
- spell-check word list (each line is a word not in the dictionary that is allowed to be in UBL, including misspellings from previous versions of UBL that cannot be repaired due to backward compatibility)
- documentary ODS template skeleton for generating spreadsheet results
skeletonDisplayEditSubset.odsraw/val- note there are 10 invocations of test files, all hardwired with the current version of UBL to point to the current set of schemas; these references need to be updated when changing to a new version of UBL
All references in the hub document UBL.xml to version, revision, and date information must be maintained in a set of general entities maintained in the internal document type subset along the lines of the following for CSD05 that followed CS01:
<!ENTITY name "UBL">
<!ENTITY pversion "2.2">
<!ENTITY version "2.3">
<!ENTITY pstage "cs01">
<!ENTITY PSTAGE "CS01">
<!ENTITY stage "csd05">
<!ENTITY STAGE "CSD05">
<!ENTITY isostage "WD">
<!ENTITY standard "Committee Specification Draft 05">
<!ENTITY stagetext "Committee Specification Draft 05">
<!ENTITY standard "Committee Specification 01xxxxxx">
<!ENTITY stagetext "Committee Specification 01xxxxxx">
<!ENTITY standard "Committee Specification Draft 04 / Working Draft 03xxxxx">
<!ENTITY stagetext "Committee Specification Draft 04 Working Draft 03xxxxx">
<!ENTITY this-loc "https://docs.oasis-open.org/ubl/&stage;-UBL-2.3">
<!ENTITY previous-loc "https://docs.oasis-open.org/ubl/&pstage;-UBL-2.3">
<!ENTITY latest-loc "https://docs.oasis-open.org/ubl">
<!ENTITY pubdate "12 May 2021">
<!--remove time from pub date-->
<!ENTITY pubyear "2021">
<!ENTITY pubdate-iso "ccyy-mm-dd">
<!ENTITY reldate-iso "ccyy-mm">
Recall that only the first declaration of a given general entity is respected. This allows prototypical declarations to be maintained after the active declaration is specified in the file.
There are a number of SYSTEM general entities whose content is not edited by hand. Rather, they are generated from the inputs of other configuration files UBL-Party-summary-information.xml and UBL-Schema-summary-information.xml that are the responsibility of the maintainer to make consistent with their expectations of the hub document.
Source files, processing stylesheets, and resulting entities generated or used in the building of the hub document - EDIT THE XML FILES ONLY DO NOT EDIT THE ENTITIES (-ent.xml) DIRECTLY AS YOUR EDITS WILL BE IGNORED:
UBL.xmlis the raw main hub document that gets massaged, assembled, and processed in the finalUBL-{version}.xml; also the authored text in Section 2.3 of this raw file is processed byhub2processSummary.xslto create the overview used in Section 2.3.1:summary-processes-ent.xml
UBL-Party-summary-information.xmlprocessed bypartydoc2db.xsl:summary-parties-ent.xml
UBL-Schema-summary-information.xmlprocessed byschemadoc2db.xsl:summary-namespaces-ent.xmlsummary-schemas-ent.xmlsummary-examples-ent.xml
UBL-{prevVersion}.xmlis the final monolithic hub document from the previous version of UBL- the artefacts building process creates the following four entity files for comparing current versions to old versions:
old2newDoc-from-previous-version-documents-ent.xmlold2newDoc-from-previous-version-library-ent.xmlold2newDoc-from-previous-stage-documents-ent.xmlold2newDoc-from-previous-stage-library-ent.xml
The old2newDoc version entities are always in play in the hub document, through to the completion of OASIS Standard. As the work proceeds in stages during working drafts and committee specification drafts, the old2newDoc stage entities are incorporated into the appendix comparing the previous stage to the current stage. Once the model has been completed and the work is progressing through Committee Specification to OASIS Standard, that stage-perspective section of the documentation is commented out and not included.
Please note the documentation above regarding ATTENTION-new-entities.txt and how to remove that file from the build process by replacing the authoring environment "old" entities with the build environment "new" entities.
Subdirectories:
images- original revisable source vector artwork in.svgor.drawio(incomplete set of files because many originals have been lost; please add originals here using same base name as published)art- high-res PNG artwork for print publishing (max width: 5.7in/14.5cm)- at a resolution of 600dpi: max width: 3425 pixels
- at a resolution of 400dpi: max width: 2283 pixels
- at a resolution of 300dpi (minimum): max width: 1713 pixels
htmlart- low-res PNG artwork for web publishing (max width: 750 pixels)os-UBL-2.0- code list subdirectory copied from released version of UBL 2.0os-UBL-2.1- code list subdirectory copied from released version of UBL 2.1os-UBL-2.2- code list subdirectory copied from released version of UBL 2.2os-UBL-2.3- code list subdirectory copied from released version of UBL 2.3raw- pre-populated content of the results directory with skeleton contentsraw/cl- code list content from having run the code list tooling and results here:- https://www.oasis-open.org/committees/document.php?document_id=67039 - tooling
- https://www.oasis-open.org/committees/document.php?document_id=67038 - results
- the
master-code-list-UBL-*.xmlfile records the input information to the code list generation
raw/json- sample JSON instances converted from the sample XML instancesraw/json-schema- hand-authored JSON Schema fragmentsraw/mod- hand-authored model documentation fragmentsraw/val- demonstration validation environment and validation of the XML samplesraw/xml- sample XML instancesraw/xsd- hand-authored XML Schema fragments- note that when changing UBL versions there are hardwired references to the UBL version number in the
common/UBL-*.xsdfiles
- note that when changing UBL versions there are hardwired references to the UBL version number in the
utilities- tools used to generate outputs
Image creation using the http://draw.io tool:
- copy
UBL-2.3-Pre-awardProcess.drawioas a starting point full-width image with your own file name - open the copy in
http://draw.ioand modify it as required - save the vector file in the
imagesdirectory - using the menu item File / Export as / Advanced...
- select PNG format
- set the DPI to 600 using "Custom"
- set the width of the image to a maximum 3425 pixels
- the zoom should be less than or equal to 100%
- of course if the image is not the full width of the page the width count can be less to proportionally less than 3425
- turn off the transparent background and any border width
- save the resulting high-res PNG file into the
artdirectory - copy the high-res PNG file into the
htmlartdirectory - using GIMP or some other pixel image manipulation tool, scale the
htmlartcopy to be a maximum width of 750 pixels (or proportionally smaller if desired) and 96 DPI
Intermediate edits saved to the local UBL.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. The preview does not regenerate the SYSTEM general entities, so it may be necessary to push your intermediate work to your branch in order to obtain replacement entity files for your repository from 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
If you are working from the GitHub web interface, every time you commit a change you will trigger a git push. If you are working from the command line you can do multiple commits before you push them to the repository.
Every git push to the repository triggers the GitHub Action execution of the build process on the files found in the repository after the push. The action takes about 25 minutes of processing on GitHub to create all of the 550Mb of artefacts. The resulting ZIP is about 160Mb and when unzipped provides the three archive, ISO, and distribution ZIP files with the results.
The results that are to be made public are posted as-is to Kavi. Please do not make reference to the GitHub artefacts in committee mail list posts as those artefacts evaporate after 90 days.
When needed, OASIS TC Administration posts the distribution package from Kavi to the https://docs.oasis-open.org/ubl OASIS web site.
Every new result snapshots in the archive-only ZIP the Google spreadsheets at the time the results were created.
If ever it is necessary to run the current publication process on an old snapshot from Google, this is accommodated by copying into the parent directory of the repository the three Google files from an archive-only ZIP:
UBL-Signature-Google.odsUBL-Library-Google.odsUBL-Documents-Google.ods
A possible (but infrequent) scenario for this is when the production and packaging have changed after the spreadsheet has changed, but the new processes need to be run on the old semantic library.
Another possible (but hopefully very infrequent) scenario for this is when it is necessary to recreate an old repository snapshot reproduction of the result after the online spreadsheets have changed. To re-run, check out the old branch to a new branch, add the ODS files from that branch's archive, and check in the new branch. The end results should be identical.
IMPORTANT: Remember to delete the Google ODS files from the parent directory in order to restart online access to the current Google spreadsheets.
If you are in a shell environment (such as MacOS Terminal) you can create the results locally as a pre-test before pushing any commits to GitHub. The invocation is:
./build.sh {results-directory} {platform} {label}
or if you have publishing credentials for the online publshing service:
./build.sh {results-directory} {platform} {label} {username} {password}
as in the following specifying "local" for the local machine and "debug" as a label to produce the results in a temporary directory:
./build.sh ~/temp/ubl-results local debug
The build result (after about 30 minutes on the GitHub Actions tab) in the target directory:
UBL-package-github-{timestamp}.zip- download package
The embedded ZIP files found in the download package:
UBL-2.x-{stage}-{timestamp}.zip- distribution artefactsUBL-2.x-{stage}-{timestamp}-iso-iec-19845.zip- publishing artefacts for ISO/IECUBL-2.x-{stage}-{timestamp}-archive-only.zip- archive artefacts
To determine if the files are ready for sending to the project editors, look in the results in the archive-only ZIP for these files summarizing any problems with the submission:
build.exitcode.{timestamp}.txt- exit code from the execution of the Ant build scriptbuild.console.{timestamp}.txt- console log of the execution of the Ant build scriptcheck-ubl-version-stage-ubl-version-pstage.html- e.g.check-ubl-2.3-csd05-ubl-2.3-cs01.html- report of differences between the current version/stage and the previous version/stagecheck-ubl-version-stage-ubl-peversion.html- e.g.check-ubl-2.3-csd05-ubl-2.2- report of differences between the current version/stage and the previous version.
IMPORTANT: If there is no console log file, then the build script failed in an unexpected fashion. Details may be found in the action tab's workflow log.
There should be no ".txt" files in the returned base directory. Various ".txt" files are possible to report problems with the build. The problems should be explained in the file itself or correlated in the build.console.{timestamp}.txt file:
ATTENTION-new-entities.txtindicates that in thearchive-only/subdirectory has anew-entities/directory with new entity files that were created by your changes to the document, schema summary, and party XML files; if there are any new entity files, you must replace your local copies with those new entities in order for the validation in your XML editor to match the validation results on the server; if thenew-entitiesdirectory does not exist, then there is no need to update your local entity files.INTEGRITY-PROBLEMS.txt- there are files referenced in the hub document that do not exist, or there are files that exist and are not referenced in the hub documentLIST-OF-PROBLEM-CODE-LISTS.txt- genericode files in thecl/directory that are not genericode-schema validMISMATCHED-TEST-SAMPLES-SH-WARNING.txt- the number of invocations in theval/testsamples.shscript does not match the number of examplesMISMATCHED-TEST-SAMPLES-BAT-WARNING.txt- the number of invocations in theval/testsamples.batscript does not match the number of examplesNDR-SPELL-CHECK-WARNING.txt- see theunexpectedWords.txtfor a list of words that are not found in English or the UBL dictionaryUNEXPECTED-SAMPLES-NS-PI-DETAILS.txt- open the file to see a list of unexpected namespace declarations found in sample filesUNEXPECTED-TEST-RESULT-WARNING.txt- theval/test.shscript did not end cleanlyUNEXPECTED-TEST-SAMPLES-RESULT-WARNING.txt- at least one invocation in theval/testsamples.shdid not validate
There should be no intermediate-support-files/ subdirectory in the returned base directory. When it exists, there were problems in the build process and the intermediate files may provide some helpful information.
When editors create their final edits, the results from the git push should be ready to be published without any modifications. If there are errant or unexpected files in the directory, the build process needs to address the discrepancies.
After having downloaded your results, please delete your entire workflow run listed in the Actions tab after you are done. This will save space and will promote the public access of the Kavi repository rather than intermediate issues.
PLEASE BE CAREFUL: ANY MEMBER CAN DELETE ANY WORKFLOW SO TRY HARD NOT TO DELETE THE WORKFLOW CREATED BY A COLLEAGUE; CHECK THE BRANCH NAMES.
- (nothing on the 'to do' list at this time)
As stated in this repository's CONTRIBUTING file, contributors to this repository are expected to be Members of the OASIS UBL TC, for any substantive 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.
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 UBL 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 file.
Please send questions or comments about OASIS TC GitHub repositories to Chet Ensign. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the UBL TC's home page.
