Admin Guide Home

GitHub Clients

GitHub Training

github.io Publishing

Asciidoctor Publishing

Publishing iTC Docs

Doc Workflow

Interpretation

Introduction

Hopefully, at some regular interval, the iTC will actually produce versions of the documents for publication. This can be drafts for internal versions (generally for consumption only by the iTC), public review versions or published documents for use.

There are several steps that should be followed to create a published version.

References

1. Merge the Working Branch to Master

Once you have the working Branch to the point where you think it is ready to publish, it should be merged into the Master branch. If you are following a process similar to that described in the Doc Workflow then the iTC should have approved the current Working branch and the Editor Team should then merge this into the Master branch.

This will update the Master (which would be blank the first time you do this, but later would have the "current" published version) to be the same as the current Working branch.

To do this, the Editor Team will follow these steps:

  1. Create a new Pull Request (this can be done from the Code tab)

  2. For the base branch, select Master

  3. For the compare branch, select Working

  4. Assuming there are no problems (it should show "Able to merge" next to the menu items)

    1. Review the comments/commits shown for inclusion (make sure it looks right)

  5. Enter in a comment (something like the version this will be and any other comments)

  6. Click Create Pull Request

    1. Members of the Editor Team should be assigned to review the changes (though ideally you are moving to this point because everyone already agreed to what is in the Pull Request)

  7. The Editor Team should review and approve the Pull Request

Once the Pull Request has been approved by the number of members necessary, the Pull Request can be merged to Master.

2. Create Published Documents

The documents that are being published need to be downloaded and be run through the Asciidoctor Generating Output process to create the documents to be published.

Depending on the purpose of the publication it may not be necessary to create both HTML and PDF output for every document.

3. Create a Release in GitHub

To mark the current content of Master as a release, you need to publish a Release within GitHub. With the creation of the Release you will also upload the "final" documents (HTML, PDFs, anything that is created outside the code in the Master) as part of the Release.

  1. On the Code tab click releases (this will have a number next to it showing the number of releases created, and will be 0 the first time)

  2. Click Create a new release

  3. In the Tag version field enter a version for the document

    1. Note the suggestions on the right side if you are unsure

  4. Make sure the Target says Master since you are publishing the Master branch

  5. Provide a title for the release

  6. Place a description of the release (especially useful if this is a draft version where the reasons for publishing may not be as clear as on a final release, also good for change lists)

  7. Add the output documents to the Release

  8. If this is not a "final" release (i.e. 1.0, 2.0), then check This is a pre-release

  9. Click Publish release

At this point the current state of the Master branch and the files you uploaded will be packaged as a release.

4. Posting the Documents for External Access

The published documents (the output from the Asciidoctor tools) and any related files should now be published somewhere. This can be to the CCUF website or to a site hosted on GitHub (see Publishing the iTC GitHub Website for more information about creating a GitHub page).