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:
xml/_workgroups.xml
- maintains the lists of all work groups that can take responsibility for JIRA feedback items.xml/_families.xml
- maintains the list of product families.
xml/SPECS_???.xml
- lists what specifications are part of a product family.
???
portion of the filename must match one of the keys specified in xml/_families.xml
- and one of these files MUST exist for each family!xml/FHIR-core.xml
) document the artifacts and pages associated with each specification.
[family key]-[specification-key].xml
.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.
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:
xml/SPECS-???.xml
file.
foo
spec to FHIR
, you would add an entry in the xml/SPECS-FHIR.xml
file that looked like this:
<specification key="foo" name="The Foo FHIR Project"/>
xml
folder.
foo
FHIR spec, you would create xml/FHIR-foo.xml
and populate it with something like this:
<?xml version="1.0" encoding="UTF-8"?>
<specification
gitUrl="https://github.com/HL7/foo"
url="http://hl7.org/fhir/foo"
ciUrl="http://build.fhir.org/ig/HL7/foo"
defaultWorkgroup="fhir-i"
defaultVersion="1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../schemas/specification.xsd"
>
<version code="1.0"/>
<artifactPageExtension value="-definitions"/>
<artifactPageExtension value="-examples"/>
<artifactPageExtension value="-mappings"/>
<artifact name="Example" key="Foo-example" id="Foo/example"/>
<page name="(NA)" key="NA"/>
<page name="(many)" key="many"/>
<page name="Table of Contents" key="toc"/>
<page name="Home" key="index"/>
<page name="Artifacts Summary" key="artifacts"/>
<page name="(profiles)" key="profiles" deprecated="true"/>
<page name="The Foo FHIR Project" key="foo" url="foo" deprecated="true"/>
</specification>
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
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.
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 $>
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.