Publish XSpec development version as Oxygen add-on

[AirQuick]

This pull request publishes a snapshot of the development version of XSpec as an Oxygen add-on.

I would like to propose publishing a new development version via this add-on channel whenever a notable change gets merged into master.

The initial add-on version is v0.0.2 which installs the snapshot of XSpec b19ccd7.
The add-on v0.0.1 exists too, but it's just for upgrade testing.

What is Oxygen add-on?

See an Oxygen page. Their video demonstrates end-user experience.

What is the development version of XSpec?

Just a specific commit version of master branch.

Where is the add-on package?

No package built. We can take advantage of this repository's queer structure. (Cloning is deploying.)

This pull request just adds an add-on descriptor file (oxygen-addon.xml). The add-on descriptor locates one of the GitHub tree zips.

Once we merge this pull request, the add-on descriptor URL will be https://github.com/xspec/xspec/raw/master/oxygen-addon.xml. We could possibly ask SyncRO Soft to XInclude our URL from their community descriptor.

Why version 0.0.z?

See a comment in oxygen-addon.xml.

How I tested it

I tested this add-on on Oxygen

• 19.0 build 2017062918
• 19.1 build 2018122811
• 20.0 build 2018042410
• 20.1 build 2018122403
• 21.0 build 2019040204
• 21.1 build 2019101513

on Windows and Linux using the following steps.

You can also follow this steps to see what will happen when we publish this add-on. If your Oxygen version is older than 19, please let me know and I'll look into what we can do.

Preparing the test

1. Make sure you don't have another XSpec installed.

   • If you have, you need to disable it before testing this pull request.
   • You may have another framework installed by one of the common methods described in Wiki.
   • If you're using XSpec Helper view add-on, its companion framework add-on takes precedence. You need to disable the companion framework.

2. Open test/xspec-variable.xspec on Oxygen.

   • Oxygen's built-in XSpec framework should take effect.
     • XSpec schema should reject x:variable.
     • Running Run XSpec Test transformation scenario should fail.

Installing v0.0.1 of the add-on

1. Oxygen menu - Help - Install new add-ons.

2. Specify https://github.com/AirQuick/xspec/raw/oxy-addon/oxygen-addon.xml in Show add-ons from box.

   • v0.0.2 of this add-on should come up.
   • Its description should tell you that this is a snapshot of the development version and should provide the changelog.

3. Do not install v0.0.2 at this time.

4. Uncheck Show only the latest versions of the add-ons.

   • v0.0.1 of this add-on should come up.
   • Again, its description should tell you that this is a snapshot of the development version and should provide the changelog.

5. Check v0.0.1 (not v0.0.2) and click Next.

   • License should be filled with the MIT License.

6. Check I accept... and click Install.

   • "Not all selected add-ons have valid signatures..." warning pops up. Click Continue anyway.

7. "To apply these changes, you must restart..." notification pops up. Click OK.

8. Close Oxygen entirely.

9. Launch Oxygen again. It may take some time.

10. "1 new update(s) are available..." notification pops up. Click Close for now.

11. Verify that the installed add-on v0.0.1 takes effect.

    • Open test/xspec-variable.xspec on Oxygen.
      • XSpec schema should recognize x:variable.
      • Running Run XSpec Test transformation scenario should succeed.
      • XSpec for XQuery using XProc transformation scenario should not be found in Transformation Scenarios pane

Upgrading from v0.0.1 to v0.0.2

1. Oxygen menu - Help - Check for add-ons updates.

   • "Update available 0.0.2" should comes up.

2. Make sure you have XSpec checked. Click Update.

3. Check I accept... and click Finish.

   • "Not all selected add-ons have valid signatures.." warning pops up. Click Continue anyway.

4. "To apply these changes, you must restart..." notification pops up. Click OK.

5. Close Oxygen entirely.

6. Launch Oxygen again. It may take some time.

7. Verify that the upgraded add-on v0.0.2 takes effect.

   • Open test/xspec-variable.xspec on Oxygen.
     • XSpec for XQuery using XProc transformation scenario should be found in Transformation Scenarios pane. Apply it to the currently opened xspec-variable.xspec. It should succeed and the report HTML should be opened.

Uninstalling the add-on

1. Oxygen menu - Help - Manage add-ons.

2. Check XSpec v0.0.2 and click the bottom left Uninstall button.

3. "Are you sure..." pops up. Click Yes.

4. "To apply these changes, you must restart..." notification pops up. Click OK.

5. Close Oxygen entirely.

6. Launch Oxygen again. It may take some time.

7. Oxygen menu - Options - Preferences - Add-ons.

8. Delete https://github.com/AirQuick/xspec/raw/oxy-addon/oxygen-addon.xml to clear the residue of this testing.

[galtm]

Will the add-on be for interim development versions only or for a mix of both development versions and official releases? Covering both sounds good to me, because if Oxygen makes the add-on process really easy, it would be a shame for that process to be unavailable to people who want the latest official release. Is it a problem if 1.5.0 ends up out of sequence between some versions 0.0.x and 0.0.(x+1)?

[galtm]

Here are a few comments from looking at the code, but I have yet to try the workflow first-hand. I plan to do that on Monday.

[AirQuick]

Will the add-on be for interim development versions only or for a mix of both development versions and official releases?

I'm thinking to treat an official release as just one of the latest snapshots of the development version. A possible release flow would be like this:

1. Add-on v0.0.1: Initial prerelease of XSpec v1.5.0. A mostly hidden version, only for upgrade testing.
2. Add-on v0.0.2: Another prerelease of XSpec v1.5.0. Introduces XSpec for XQuery using XProc transformation scenario (Add Oxygen XQuery XProc transformation scenario #736).
3. Add-on v0.0.3: Yet another prerelease of XSpec v1.5.0. We may call it an RC. Introduces the rest of the user-visible enhancements.
4. Add-on v0.0.4: The official release of XSpec v1.5.0 (assuming the add-on v0.0.3 did not have a critical problem). Create this add-on release at the same time as we do Create a pull request adding SNAPSHOT in pom.xml and merge it into master described in Wiki.
5. Add-on v0.0.5: Initial prerelease of XSpec v1.6.0. Introduces a certain user-visible enhancement such as TVT (feat: support Text Value Templates (expand-text) #711)
6. Add-on v0.0.6: Another prerelease of XSpec v1.6.0. Introduces another user-visible enhancement such as Schematron schema (feat(schema): add Schematron schema for XSpec #742)
7. ...
8. Add-on v0.0.10 (or some such): The official release of XSpec v1.6.0
9. Add-on v0.0.11: Initial prerelease of XSpec v2.0.0. Throws away Saxon 9.7 and use XSLT 3.0 by default.
10. Add-on v0.0.12: Another prerelease of XSpec v2.0.0. Introduces a certain user-visible enhancement we do not know yet.
11. ...

What do you think?
(ccing @cirulls)

[galtm]

@AirQuick , your plan sounds good to me. Thanks for the clarifying answers to my questions.

[galtm]

I tried the workflow you outlined (on Windows with v21.0, build 2019022207) and everything worked smoothly. I don't have any comments beyond what I posted the other day.

[AirQuick]

Thanks @galtm for reviewing this.
I updated Wiki to reflect this change.

[galtm]

The wiki looks great! I changed only one sentence to clarify the notification/update process.

[AirQuick]

3. Add-on v0.0.3: Yet another prerelease of XSpec v1.5.0. We may call it an RC. Introduces the rest of the user-visible enhancements.

Submitted as #751

[cirulls]

@AirQuick: The procedure in #743 (comment) looks good to me. Thanks for updating this Wiki page.