HL7 / JIRA-Spec-Artifacts

Manages the artifacts, pages and other lists associated with all HL7 projects managed through JIRA feedback projects
9 stars 112 forks source link

JIRA-Spec-Artifacts

This project manages the artifacts, pages, and other lists associated with all HL7 projects managed through JIRA feedback projects.

Read more about it here: https://confluence.hl7.org/display/HL7/Configuring+Specification+Feedback

To make pull requests against this project, create a fork in your personal Github space and submit a pull request from there. (Most users will not have permission to create branches directly within this project.)

Source content is found in the xml folder:

Each type of XML file has a corresponding schema in the schemas folder. The xml/_workgroups.xml file is also converted to a schema to aid validation.

The json files used by the Jira Elements Connect (formerly nFeed) plugin to manage dropdowns are auto-generated into the json folder. There is one file for each product family plus a single "combined" file that covers all specifications and is used by the ballot projects None of these files should be manipulated directly as they'll be overwritten. An additional file called tools/SPECS.xml is used to help ensure that keys aren't accidentally deleted or changed.

NOTE: any key used by any Jira tracker items must NEVER be removed or changed. Removal of other keys should be handled by an administrator.

Adding a New Spec Artifact

When building a new IG, you may encounter a warning in your qa.html that looks like this:

The jira specification file appears to be out of date with the versions, artifacts and pages 
currently defined in the IG.  A proposed revised file to be reviewed and, if appropriate, 
submitted as a pull request against the XML folder in https://github.com/HL7/JIRA-Spec-Artifacts.

To address this, you must make sure that:

It is recommended that you create a new branch (in this example, you might call it add-foo).

Once your files are added to your branch, please also confirm that your new artifacts are not causing any new build errors or warnings. A workflow will run against you branch for each commit and the output will be available here (update your branch name in the link): https://github.com/HL7/JIRA-Spec-Artifacts/actions?query=branch%3Aadd-foo

screenshot

Finally, when you have built your IG using the publisher locally, it may emit a generated artifact xml file for you to add to this repo. So, if you have that file in your build directory, you can add your generated xml to this repo without having to write one manually.

Building

This JSON artifacts of this project can be built manually on the command line like this:

bash $> java -jar ./tools/ant/ant-launcher.jar
Buildfile: ~/code/JIRA-Spec-Artifacts/build.xml

validate:
     [xslt] Processing ~/code/JIRA-Spec-Artifacts/xml/_workgroups.xml to ~/code/JIRA-Spec-Artifacts/schemas/workgroups.xsd
     [xslt] Loading stylesheet ~/code/JIRA-Spec-Artifacts/tools/buildWGschema.xslt

genJson:
    [mkdir] Created dir: ~/code/JIRA-Spec-Artifacts/json
    [mkdir] Created dir: ~/code/JIRA-Spec-Artifacts/tools/temp
     [xslt] Processing ~/code/JIRA-Spec-Artifacts/xml/_families.xml to ~/code/JIRA-Spec-Artifacts/json/families.json
     [xslt] Loading stylesheet ~/code/JIRA-Spec-Artifacts/tools/xmlToJson.xslt
     [xslt] Processing ~/code/JIRA-Spec-Artifacts/xml/_workgroups.xml to ~/code/JIRA-Spec-Artifacts/json/workgroups.json
     [xslt] Loading stylesheet ~/code/JIRA-Spec-Artifacts/tools/xmlToJson.xslt
      [get] Getting: https://hl7.github.io/JIRA-Spec-Artifacts/SPECS.xml
      [get] To: ~/code/JIRA-Spec-Artifacts/tools/temp/SPECS.xml
     [xslt] Processing ~/code/JIRA-Spec-Artifacts/xml/_families.xml to ~/code/JIRA-Spec-Artifacts/json/SPECS.json
     [xslt] Loading stylesheet ~/code/JIRA-Spec-Artifacts/tools/buildSpecJSON.xslt

test:

BUILD SUCCESSFUL
Total time: 2 seconds
bash $> 

Automatic Deployments

There is a GitHub Action defined to automatically build and deploy the JSON files from the master repo into the gh-pages branch upon every commit to the master branch. For this to work, a deployment ssh key has been defined and added to the repository settings. You must be an admin of the repo to make changes to this key.