Add release workflow, README and CONTRIBUTING files (#2)

.github/workflows/release.yml

@@ -0,0 +1,59 @@
+# Workflow for building and deploying an asciidoctor site to GitHub Pages
+name: Deploy asciidoctor site to GitHub Pages
+
+on:
+  # Runs on pushes targeting a tag
+  push:
+    tags:
+      - "v*"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2" # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+      - run: |
+          gem install asciidoctor 
+          asciidoctor docs/index.adoc -D output
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          # Upload entire repository
+          path: "./output"
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

CONTRIBUTING.md

@@ -0,0 +1,17 @@
+## Publishing a new version
+
+### Creating a GitHub Release
+
+Check the version number of the latest [GitHub release](https://github.com/BerryCloud/xapi-player/releases).
+
+Draft a [new GitHub release](https://github.com/BerryCloud/xapi-player/releases/new) with the next version number.
+
+Select `Choose a tag` and type the new version number prefixed with `v` and select `create new tag: v*.*.* on publish`.
+
+Ensure that the target branch is `main`.
+
+The release title should be the new version number prefixed with `v`.
+
+Publish the release.
+
+Once the GitHub release has been created, GitHub actions will publish the new version of the documentation to the [github pages site](https://berrycloud.github.io/xapi-player/).

README.md

@@ -0,0 +1,28 @@
+# xAPI Player
+
+xAPI Player defines the JSON structure of a course or unit and can help when developing an authoring tool and implementing a course player.
+
+It can be used when creating an implementation that sends xAPI statements to a Learning Record Store (LRS), defining when the learner has met the requirements for sending statements for certain xAPI verbs. The JSON definition may also be used when implementing the cmi5 specification, defining the pass and completion of a unit.
+
+View the [documentation](https://berrycloud.github.io/xapi-player/)
+
+## Reporting Issues
+
+xAPI Player uses GitHub's issue tracking system to record bugs and feature requests.
+If you want to raise an issue, please follow the recommendations below:
+
+- Please search the [issues](https://github.com/BerryCloud/xapi-player/issues) to see if someone has already reported the bug or requested the feature.
+- If the issue doesn't already exist, [create a new issue](https://github.com/BerryCloud/xapi-player/issues/new).
+- Please use the appropriate issue template and provide as much information as possible.
+
+## Contributing
+
+Contributions are always welcome. If you discover errors or omissions, please submit an issue or open a pull request with a fix.
+
+Here are some ways you can contribute:
+
+- by reporting bugs
+- by suggesting new features
+- by writing or editing documentation
+- by fixing [issues](https://github.com/BerryCloud/xapi-player/issues)
+- by reviewing pull requests

documentation/block.adoc → docs/block.adoc

@@ -47,8 +47,6 @@ The `type` property is used to determine the type of the `Block`. The type of th
 
 Once a block is done it cannot be undone. 
 
-== Block Types
-
 [#accordion]
 === Accordion
 

documentation/container.adoc → docs/container.adoc

@@ -15,15 +15,15 @@ A collection of ordered blocks that the learner can navigate through.
 | `name` | https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#42-language-maps[LanguageMap] | Name of the container | Yes
 | `activity` | https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#activity-definition[Activity]  | Activity of the container | No
 | `unitCompletion` | boolean | If true, the unit will be considered complete when the  container is done | No
-| `blocks` | xref:block.adoc#Block[`Block`] `array`  | Blocks of the container | Yes
+| `blocks` | xref:block.adoc#block[`Block`] `array`  | Blocks of the container | Yes
 |===
 
 [discrete]
 === Restrictions
 
-There **must** be at least one xref:block.adoc#Block[`Block`] in the `blocks` array.
+There **must** be at least one xref:block.adoc#block[`Block`] in the `blocks` array.
 
-In the xref:unit.adoc#Unit[`Unit`], there **must** be at least one `Container` with `unitCompletion` set to `true`.
+In the xref:unit.adoc#unit[`Unit`], there **must** be at least one xref:container.adoc#container[`Container`] with `unitCompletion` set to `true`.
 
 [discrete]
 === Details 

docs/image.adoc

@@ -0,0 +1,23 @@
+== Image
+
+An image to display for the unit or within an HTML block.
+
+[discrete]
+=== Parameters
+
+[cols="1,1,1,1"]
+|===
+| Name | Type | Description | Required
+| `url` | string | The URL of the image | Yes
+| `description` | string | The description of the image | No
+| `author.name` | string | The name of the author | No
+| `author.homepage` | string | The homepage of the author | No
+| `provider.name` | string | The name of the provider | No
+| `provider.homepage` | string | The homepage of the provider | No
+| `blurhash` | string | The blurhash of the image | No
+|===
+
+[discrete]
+=== Restrictions
+
+The `url` property **must** be a valid URL.

documentation/index.adoc → docs/index.adoc

@@ -2,13 +2,17 @@
 Thomas Turrell-Croft; Katie Noake; István Rátkai
 :toc:
 :toclevels: 2
+:toc: left
 
 include::unit.adoc[]
 
+include::path.adoc[]
+
 include::container.adoc[]
 
+include::block.adoc[]
+
 include::image.adoc[]
 
-include::path.adoc[]
 
-include::block.adoc[]
+

documentation/path.adoc → docs/path.adoc

@@ -1,3 +1,4 @@
+[#path]
 == Path
 
 A path is a collection of ordered containers that a learner can navigate through.

docs/unit.adoc

@@ -0,0 +1,42 @@
+[#unit]
+== Unit 
+
+The launchable learning content containing a collection of ordered containers that the user can navigate through.
+
+[discrete]
+=== Parameters
+
+All units have the following parameters:
+
+[cols="1,1,1,1"]
+|===
+| Name | Type | Description | Required
+| `version` | string | Version of the unit definition | Yes
+| `name` | https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#42-language-maps[LanguageMap] | Name of the unit | Yes
+| `description` | https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#42-language-maps[LanguageMap] | Description of the unit | Yes
+| `activity` | https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#activity-definition[Activity]| Activity of the unit | Yes
+| `image` | xref:image.adoc[Image]  | Image of the unit | Yes
+| `primaryColor` | string | Primary color of the unit | Yes
+| `accentColor` | string | Accent color of the unit | Yes
+| `warnColor` | string | Warn color of the unit | Yes
+| `sectionTitle` | https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#42-language-maps[LanguageMap] | Title of the main path | No
+| `containers` | xref:container.adoc#container[`Container`]`array` | Containers of the unit | Yes
+| `help` | xref:container.adoc#container[`Container`]`array`  | Help path of the unit | No
+| `paths` | xref:path.adoc#path[`Path`]`array`  | Additional paths of the unit | No
+|===
+
+[discrete]
+=== Restrictions
+
+There **must** be at least one xref:container.adoc#container[`Container`] in the `containers` array. 
+
+At least one of the xref:container.adoc#container[`Container`] objects **must** have the `unitCompletion` property set to `true`.
+
+[discrete]
+=== Details
+
+A unit is considered completed when at least one of the xref:container.adoc#container[`Container`] objects which has the `unitCompletion` property set to `true` is done.
+
+A unit is considered passed if a xref:block.adoc#questionnairePart[`QuestionnairePart`] has the `unitPass` property set to `true` and the user has passed the questionnaire part.
+
+If a unit has a `help` path, an implementation **should** provide a way for the user to access it.