Requesting a github repository for new CDA standard projects

1. Register an account on github
2. Request a new github repository for your CDA standard project from webmaster@hl7.org
   1. Name should start with "cda"
   2. Version of the standard should NOT be in the name
   3. 
3. The HL7 webmaster will get back to you when the repository has been completed with the full path to the new repository:

How to populate a CDA github repository

Repository folder guidance

All CDA implementation guide github repositories should include at least the following folders at the top level of the repository:

1. examples - containing XML example files, and potentially HTML rendered versions of those examples
2. input - containing raw source files used to develop the HL7-hosted publication package, usually MS Word files, and potentially PPT, Visio, or other graphics source files important to the future maintenance of the standard
   1. Note: CDA IG drafts are often created as MS word files and sent out for review before final publication as PDFs. The HL7 Board has discussed the potential IP concerns around including these Word docs on GitHub and determined that there are no issues with including the “source files” (be they Word, PDF, XML, HTML, images, JSON, etc) in a working repository that has public read access and controlled write access.
   2. These files can be added to GitHub without IP-specific restrictions (for instance, there's no need for a 90-day hold before posting them to GitHub). This also applies to things besides draft IGs, like errata publications and artifacts.
3. validation - containing schematron validation scripts corresponding to the implementation guide

Github desktop instructions

If using github desktop, the following steps can be used to populate this repository using files prepared locally:

1. From the top left - select "Add" → "Clone repository..."
   • 
2. Select the URL tab, enter the URL provided to you for your github repository by the HL7 webmaster, and click "Clone"
   • 
3. The github repository is still empty, but open the folder to which it has been cloned by clicking the "Show in Explorer" button:
   • 
4. After staging the files you'd like to post to the github repository by copying them into the folder opened in the previous step, github desktop will show a summary of file changes.  At the bottom left, enter a "Summary" and "Description" to be logged with these file changes, and click the "Commit to main" button:
   • 
5. At the top right, click on the box to "Push origin" to post your changes to the github repository:
   • 
6. Your repository should now be populated with the files you staged locally

Creating a Release

It's recommend to create a github release to make it easy for implementers to find and download a package of supporting files corresponding to a particular release of a standard:

1. At the bottom right of your github repository page, click on the "Create a new release" link:
2. 
3. On the create release page, take the following steps:
   1. From the "Choose a tag" dropdown, enter an appropriate tag to be created on publication for the release (you may want to consider "v1" for the initial setup related to a standard)
   2. Enter an appropriate title for the release
   3. Populate the description of the release
   4. Click the "publish release" button - this will automatically attach a full copy of the current contents of the repository to the Release
      • 
4. Your new release should show up at the center right of the github repository main page:
   • 

How to update a CDA github repository when a new version of the standard is published

As a new version of the standard is approved to be published, updated versions of supporting files in github should be replaced directly, as github will manage the version history for files. New versions of existing files should NOT simply be added with new dates in the names. An elegant process to follow is to create a new Branch for the new version of the standard, populate that branch with the appropriate updated files, and then merge that Branch back into the main branch if desired.

Creating a branch

1. Create the new branch - click on the "Current branch" tab at the top of Github desktop, and click the New Branch button
   • 
2. Enter an appropriate name for the new Branch and click "Create branch":
   • 
3. Click the "Show in Explorer" button to open the local folder where the new Branch content resides. This folder will still be populated with the previously-published versions of files.
   • 
4. Replace/edit files in this local folder as appropriate to correspond to the new version of the standard
5. Click the "Publish branch" button to create the new branch on github, and upload your revised files
   • 
6. Your new branch will now be available on github, by clicking on the "main" branch indicator dropdown:
   • 

Merging a branch into main

If your standard will not require separate versions to evolve independently of one another (e.g., actively apply errata changes to BOTH an old version and a new version of supporting files at the same time), you likely will want to merge the branch associated with the new version of the standard into the main branch.

1. Select the new branch by clicking on the "main" branch indicator dropdown on the github repository page:
   • 
2. Click on the "Compare & pull request" button for the new branch:
   • 
3. At the top left of the next page, you'll see that the new branch (in this case "R2") is being merged into the base branch (in this case "main") - click "Create pull request" to initiate this merge request.
   • 
4. Click on the "Merge pull request" button on the next page to process the merge request. and then "Confirm merge" to apply changes.
5. The contents of the "main" branch should now reflect the content from new branch. If you no longer need the new branch, you can delete it using the "Delete branch" button presented at the end of this process:
   • 
6. Now that the new supporting files for the new version of the standard have been posted, you should create a new Release following the instructions above.