This document describes the life cycle and process for developing Engineering Reports (ERs) during OGC Innovation Program (IP) testbed initiatives. This process may also be used in other IP initiatives, but it is intended primarily for testbeds.

The process promotes the creation of work products that more effectively advance the OGC Standards Baseline, affording the OGC SWGS and DWGs an opportunity to influence the recording of testbed outcomes in the delivered ERs.

This document includes the following sections:

Editing ER Source Content

In general, any testbed Participant could be required to directly contribute ER content. So every testbed contributor should be familiar with the source content editing tools.

AsciiDoc Tooling

Source content will be authored using the Asciidoc language and the OGC ER Template, which contains an integrated starter-set of Asciidoc source files.

Testbeds typically generate a substantial volume of documentation to be consumed in a very brief time period. A uniform approach across all ERs will reduce the heavy burden on reviewers. A request for an exception will be considered if a deviation is needed (e.g., the deliverable will be a draft specification rather than an ER).

Otherwise, to ensure uniformity, extensive editing rules have been included in the ER Template. In particular, general editing guidelines are provided at the top of the main er.adoc file. Unless an exception has been granted, these guidelines are mandatory.

Likewise, the Example Clause in the 5-example.adoc file explains concepts frequently required by Asciidoc novices. As with the editing rules, unless an exception has been granted, these guidelines should be considered mandatory. More extensive reference material is available in the AsciiDoc User Guide and the AsciiDoc Cheat Sheet.

An improved (mandatory) approach based on asciidoctor-bibtex was adopted for Testbed-14. Under this approach (also described in the ER Template file annex-bibliography.adoc), the ER bibliography will be automatically built. All the author needs to do is to provide the citation information in the file /resources/bibtex-file.bib.

Then citation keys can be added anywhere in the text using the pattern cite:[NameYear] (for example, cite:[VanZyl2009]).

Compiled output can be generated using the command asciidoctor -r asciidoctor-bibtex er.adoc.

For testbed stakeholders wishing read-only access to the latest ER versions, HTML and PDF outputs will be regularly harvested from GitHub and made available. The source code will remain active in the repo until the OGC Technical Committee (TC) approves publication.

Recommended Asciidoc Environment

We recommend to use asciidoctor and asciidoctor-pdf in combination with the Atom editor.

Installation on MacOS and Linux

  1. Please follow the steps on https://asciidoctor.org/#installation.

  2. Install the bibtex extension: gem install asciidoctor-bibtex

Installation on Windows

We have made best experiences with the following steps:

  1. Install ruby for windows: https://rubyinstaller.org/downloads/. If you experience any issues, the following link may help: stackoverflow

  2. Open command prompt and install two gems:

    1. Execute: "gem install asciidoctor"

    2. Execute: "gem install asciidoctor-bibtex"

  3. Text your installation

    1. Open a folder that contains your Engineering Report asciidoc source files, including the er.adoc file.

    2. Execute the following command: asciidoctor -r asciidoctor-bibtex er.adoc

Using Asciidoctor with Atom

In Atom, you should install the following packages:

  • asciidoc-preview

  • autocomplete-asciidoc

  • language-asciidoc

  • markdown-writer: requires changing of key-map to allow for keyboard shortcuts such as e.g. bold

  • platformio-IDE-terminal

This environment allows you to use keyboard shortcuts, autocomplete, syntax highlighting and a rendered preview for asciidoc; and provides you an terminal window within the editor to convert your asciidoc to html and pdf.

Asciidoc Conversion

In order to achieve a uniform look-and-feel of all ERs in both HTML and PDF, we have provided a css and theme file. The following commands can be used to convert the ER:

Command for PDF output: asciidoctor-pdf -r asciidoctor-bibtex -a pdf-stylesdir=resources -a pdf-style=ogc -a pdf-fontsdir=resources/fonts er.adoc

Command for HTML output: asciidoctor -r asciidoctor-bibtex -a linkcss -a stylesheet=rocket-panda.css -a stylesdir=https://portal.opengeospatial.org/files/?artifact_id=80065 ER_development_process_asciidoc_source.adoc

GitHub Tooling

A private GitHub repository ("repo") will be provided for each ER to be delivered. For reference, each ER repo will be contained in the full OGC repo of repos.

Any contributor who does not already have a GitHub ID should first join GitHub to create one. Then to access OGC GitHub repos through the Portal, please consult the instructions to obtain a GitHub ID and add it to the Portal.

Once the GitHub ID has been registered in the Portal, a contributor can gain access to an individual, private ER repo by opting-in at the Testbed-14 Portal Project.

In order to add or modify ER source content, a contributor should be capable of performing the following tasks (or equivalent):

  • If the Mac Git Bash command-line tool is preferred, be able to perform the steps described under the Git basics.

  • If a graphical interface is preferred, be able to perform the steps described under the GitHub Desktop basics.

  • Once the GitHub ID is registered in the Portal, gain access to the appropriate private repo such as the D001 ER.

    • Please be sure to access the correct ER before starting to edit its content.

  • Please find and follow all of the many editing instructions and guidelines (described above) in editing the source content.

  • Upload the source-content edits to the repo. Here’s a sample sequence of Git command-line steps (some of these are combined under a single click in GitHub Desktop):

    • Use cd to change to directory where source code will reside locally

    • git clone https://github.com/opengeospatial/D00n …​ to the remote ER repo.

    • git branch [local-name] to create a branch on the local repo copy in the current directory

    • git checkout [local-name] to enable local editing

    • Make the desired edits

    • git add --all to add all the edits to the local staging area

    • git commit -m "[informative comment…​]" to commit the changes to the local repo

    • git push --set-upstream origin [local-name]

    • Navigate to the remote GitHub repo at https://github.com/opengeospatial/D00n …​ and create a Pull Request to merge this Commit.

  • Coordinate with the ER Editor to ensure that the Pull Request is properly reviewed and acted upon.

    • An Editor may, at their discretion, grant you permission to merge the Commit yourself.

  • Clean up by deleting the branch.

The ER Life Cycle

The ER life cycle consists of a series of distinct stages, any of which may undergo multiple iterations as part of testbed execution.

The Initial ER (IER) Stage

  1. The first step is for the Editor to obtain an official OGC Document Identifier, with format "OGC YY-nnn" (e.g., OGC 17-067). This identifier can be obtained in the OGC Portal and should be loaded into the Editor’s front matter elements near the top of the er.adoc file in the Asciidoc source content.

  2. The selected ER Editor should then inquire with the most relevant SWG or DWG to obtain a commitment to provide reviews at various life-cycle stages. In some cases the target WG will be obvious (e.g., the GeoPackage SWG for GeoPackage deliverables), but the Editor can confer with the OGC Innovation Program Team (IP Team) if an appropriate choice isn’t apparent.

  3. The selected WG might ask for a brief overview of the ER requirements. In most cases, the Editor can just reference the CFP and further elaborate on any additional decisions that were made during the Kickoff.

  4. The Editor should request a formal "review approval" from the selected WG no later than three weeks after the end of the Kickoff. A Google milestone tracking sheet will be provided where the Editor can enter a record of the WG approval; the thread architect should also be notified.

    1. Please consult the Sample Letter Requesting a Review from a SWG or DWG for language that can be used as a starting point for contacting the chair(s) of the selected WG.

  5. Once WG approval has been obtained, the ER will officially become a draft "IER".

    1. The ER Editor should consider additional opportunities to maintain communication with the WG. For example, the Editor should join the WG mailing list in the Portal and could consider making a presentation to WG members who have signed up as testbed Observers.

  6. The Editor should work diligently to ensure that the IER content follows the procedures, format and guidelines provided in the Template on which each ER is based. Each ER is pre-loaded with the latest version of the Template so that the Editor doesn’t have to worry about building it. Emphasis should be placed on recent WG deliberations and how the expected testbed findings will likely impact future WG decision-making. The final iteration of the IER (likely a very light document) should then be forwarded to the WG for its first official review.

    1. Testbed-14 deadline: 31 May.

The Draft ER (DER) Stage

  1. Once the Editor has integrated all the WG feedback on the IER, the document will become a preliminary "Draft ER" (DER), which should also be developed in multiple iterations.

  2. The Editor is expected to take the lead as the primary ER author. This will require that the Editor proactively engage component implementation providers to gather technical details and reformulate it into English prose for inclusion in the body of the ER. A formal technical artifact such as an Abstract Test Suite, an XML Schema, or a snapshot of a UML Model can be imported into one of the ER appendices (included in the Template for this purpose).

  3. About 1-2 months after the IER milestone, an intermediate testbed "IER-to-DER Status Check" milestone will be used by the thread architect to monitor progress and determine whether any remediation steps are needed to recover the delivery schedule.

    1. Testbed-14 deadline: 31 July.

  4. About 1-2 months after the IER-to-DER Status Check milestone, the Editor should deliver a "Preliminary DER" for review by the thread architect and other internal testbed stakeholders (e.g., Sponsor representatives and other OGC staff). This version should be complete, with no missing content (though the content that’s there may still be in draft form). This version should also be clean, in the sense that all known defects (even misspellings and grammatical errors) should have been corrected.

    1. Testbed-14 deadline: 30 September.

  5. Planning ahead, the Editor should work with the chosen WG to schedule a meeting (if necessary) to present the DER, which is expected to soon (in a couple weeks) be posted to Pending.

  6. The Editor should update the Google milestone tracking sheet to reflect the fact that the DER has been delivered to the thread architect for internal testbed review.

    1. Upon completion of the thread architect review, the "ER reviewed by thread architect" box should be checked in the tracking sheet.

  7. The Editor should incorporate the feedback from the thread architect (and other internal testbed stakeholders) and then upload this testbed-reviewed version to the Portal Pending Documents for WG review. This will be another milestone in the testbed schedule.

    1. Testbed-14 deadline: 31 October.

  8. The Editor should then immediately make a formal review request of the chosen WG, this time to review the full DER posted in Pending.

  9. The Editor should update the Google milestone tracking sheet (check the "ER uploaded to Pending" box) to reflect the fact that the DER has been uploaded to Pending and the WG review has been formally requested.

The Public ER (PER) Stage

  1. Hopefully any remaining edits would be minor at this point, and incorporating WG feedback could take place rapidly. The reworked DER should be re-posted in Pending as quickly as possible, no later than the date for meeting the 3-week rule to be acted upon (by the WG and the full TC) at the upcoming TC Meeting.

    1. Testbed-14 deadline: 21 November.

  2. The Editor should present the ER (in-person or remotely) to the WG and update the tracking sheet (check the "ER presented at SWG/DWG meeting" box).

  3. The WG would most likely vote "YES with friendly amendments" and produce a motion for the TC to vote for release approval. The Editor should update the tracking sheet (check the "WG YES vote" box).

  4. If a WG vote at the TC Meeting isn’t workable, the ER can be approved via email vote (eVote) any time after the WG approves its release for TC vote. The eVote would last two weeks and does not require Planning Committee (PC) approval.

    1. The Editor should inform the thread architect that the presentation at the virtual working group meeting has been successful and request that the thread architect start the eVote procedure.

    2. News that the eVote has been concluded successfully will be provided to the thread architect, who will notify the Editor, who should update the tracking sheet (check the "TC approved" box).

  5. The Editor should implement any friendly amendments, update the "ER ready for publication" box, and inform the thread architect (who will provide notification that the final review is complete and publication of a Public ER (PER) can be made).

Sample Letter Requesting a Review from a SWG or DWG

Dear ... ,

I am part of a team working on the . . . Thread in OGC Testbed nn to author an Engineering Report (ER) on the subject of ...

As you may be aware, the testbed ER Process (https://portal.opengeospatial.org/files/?artifact_id=73351) requires editors to approach a relevant SWG or DWG for two reasons. The first reason is to learn about the latest discussions on any subject relevant in the context of this ER. The second is to request that the SWG or DWG commits to a future review of the ER.

I am writing to request that you (members of the . . . SWG/DWG) perform such a review, particularly the draft language describing what this ER Means for the WG.

Please let me know if you would be interested in providing this support, and I'll send you our draft Initial ER (IER) for your group’s review.

[optional] The OGC document number nn-nnn has been reserved for the document with title "Testbed-nn . . . -ER.

[optional] To give you a better understanding of the background, a related ER from Testbed nn can be downloaded from . . .

Thank you in advance for your time and consideration.

Regards,

ER editor

< end of document >