There has been a new dawn for the Lucid Protocol Specification with the specification undergoing a format change. This article explains what that change is and why the change was made. It also describes how you can access the various formats of the Protocol Specification, now.

Background to the changes

All material for the Lucid Protocol Specification is stored in a publically accessible GitHub repository, https://github.com/LucidProtocol/Lucid-Specification. The tool that underlies GitHub, “git”, is used as the version control system for the Lucid Protocol Specification.

The Lucid Protocol Specification has up till now, been mastered in a Word document within that repository. The Word document was not very convenient for reviewing changes made to the specification. The Word document appears as a binary blob to git, this does not allow git’s diff mechanism to show differences easily. The team responsible for the specification decided that they wanted the specification to be available in another format that was more conducive to git diffs and the change process within GitHub. This would permit a more efficient review process, with changes easily visible within GitHub’s Pull Request process. The team decided on Markdown.

Switching to Markdown

As well as the Word document, the repository originally contained

• A PDF version of the Word document for users convenience
• Some source pictures used within the specification, and
• The JSON and JSON Schema files which support the specification.

The diagram below shows how those files have changed in the new version of the repository to support Markdown instead of the Word document.

The main changes are that:

• The Word document and PDF document have been removed from the repository.
• A folder call Doc has been introduced containing the many Markdown files which replace the Word document.
• A folder called diagram-sources has been introduced which includes diagrams that were not placed anywhere else.
• The JSON and JSON Schema files have remainded untouched.
• A GitHub action has been added to create a GitHub Pages version of the specification
• That same action also generates a copy of specification as a PDF

The github action runs when a GitHub Pull Request (PR) is merged into the master branch of the repo. It partially runs when the PR is created to check that the document creation does not fail with the changes in the PR. It would also run if the repo was tagged by a maintainer.

Accessing the specification

The current version

To access a readable copy of the current specification including all changes in progress, click on the link at the top of the About section at the top left of the GitHub repo window, as shown below:

This will bring you to the GitHub pages version of the document which can be navigated from the panel on the left of the document, an example of this after navigating to Section 2.1 is shown below:

The last section in that Pages version of the specification is a link to the PDF version of the same document, as shown below:

There is also a link to the documentation in the README.md on the repository page as shown below:

A specific version

If you would like to access a specific version of the specification, for instance if you are developing and have selected to implement a specific version, then the Pages version of the document and the PDF will be available for that version by following the relevant Releases link, as shown below:

The same versioned information will be available from the Lucid Protocol website under the documentation section.

Working with the Markdown content

The Markdown within the docs folder in the repository, is broken up into roughly equal size files of Markdown. Where a section is large it will have a folder to itself with further files within it. As Markdown is textual,  GitHub is easily able to compare the files and show differences. When looking at a Pull Request (PR), the last tab on the PR “Files Changed”, will show each changed file and what has changed in the file in a clear format.

Instructions on how to work with the specification are laid out in the CONTRIBUTING.md tab in the repository. Please read these carefully before making any changes.

If you are editing part of the standard in Markdown, please refer to the GitHub Markdown reference page for a guide on what Markdown syntax is appropriate.

Finally …

We are keen to have others involved in the development of the Lucid Protocol Specification. Please feel free to raise issues in the repo for discussion with the team. If you want to get closer involvement, have more sway in the development of the protocol and access to other private repositories we maintain then please consider joining the WITS-PSA who manage the Lucid Protocol.  We look forward to working with you.