Defining New Information Exchanges and Editing Existing Exchanges

Contents
Defining a USGIN Information Exchange
Detailed outline for setting up a new information exchange
Checklist for repository steward
Repository management
Creating a new version (editing an existing content model)

Defining a USGIN Information Exchange

The decision to define a new information exchange should be based on the likelihood that others will want to publish similar datasets in the future. Members of the USGIN community have broadly developed specifications for data sharing exchanges, and the users community is tasked with populating new exchanges based on these specifications as needed. Exchange documents are developed and reviewed using a publicly accessible repository on GitHub (https://github.com/usgin-models). Each exchange has a separate repository associated with the usgin-models organization. A proposed model must have an identified steward and a working group of at least three participants with relevant domain knowledge and understanding of the interchange technology. There is no formal process for defining workgroup membership; normally the challenge is finding a sufficient number of qualified individuals to provide meaningful reviews and comment. The exchange steward is responsible for assembling the workgroup and assuring sufficient expertise in the group to generate a sound content model and implementation. The steward creates a new repository at the usgin-models GitHub organization and identifies workgroup members who will have commit privileges on the repository. Any community member can create a repository branch to propose changes using standard GitHub procedures, and request consideration for merging back into the developing model (see the Section Creating a new version (editing an existing content model).

After review and approval by the workgroup, a call goes out to a USGIN technical review e-mail list or by RSS feed (http://notifications.usgin.org/) for comments from the community. An open review period of 4 weeks is normal, after which any comments from the community must be resolved to the satisfaction of the commenter. When issues are resolved to the satisfaction of the stakeholders (workgroup and engaged community), the exchange specification is adopted.

When a specification is adopted, all associated documents are copied to a 'tag' branch in the GitHub repository and are not changed after they are 'tagged'. The specification documents are also copied to the exchange repository at http://schemas.usgin.org, which is a web site set up to provide public access to exchange specifications and any related xml schema documents or other artifacts required for the deployment and operation of the information exchange.

Detailed outline for setting up a new information exchange

1. Steward assembles workgroup, defines scope of model, and gets repository set up on usgin-models GitHub at https://github.com/usgin-models. E-mail models@usgin.org to request a new repository.
2. Workgroup defines content model. The recommended procedure is to scope the model based on stated target use scenarios and on example datasets that the interested parties want to share. When creating a content model draft, please see https://github.com/usgin/usginspecs/wiki/Content-Model-Guidelines. To gather interested individuals, the USGIN Notifications system via RSS feed may be used at https://github.com/usgin/service-notifications/issues where new a new issue is posted to introduce the proposal.
3. Get review of workgroup draft from community of expected users. Revise content model as necessary and post drafts in the GitHub repository.
4. Select interchange service protocol. This should be based on the availability of server and client software in the community of users. Some example possibilities include OGC WFS, WMS, WCS, OpenDAP/NetCDF/THREDDS, Microsoft OData, ESRI Geoservices API.
5. Implement the content model using an encoding scheme compatible with the chosen service protocol, e.g. XML, JSON, turtle, csv.
6. Define validation rules for instance documents.
7. Document the content model, interchange format, service protocol, and any special conventions or profile. Specify how data access links to data exposed using this exchange will be described using the metadata fields in USGIN profile ISO19139 CI_OnlineResource elements. Use existing identifiers where possible to identify service and MIME types.
8. Deploy an example service and test with client software. Iterate 1-5.
9. Have documentation reviewed by target users and technical experts; respond to comments, updating 1-7 as necessary. If using USGIN Notifications, post comments on the open issue to alert the working group and/or community to ensure all parties have commented.
10. Adopt content model for implementation. Tag the version of the content model and specification documents in the GitHub repository, and notify models@usgin.org that the exchange specification is ready. After a review for conformance with these recommendations, the repository manager will deposit specification documents in USGIN exchange repository at http://schemas.usgin.org/models to make them available to the public.

Checklist for repository steward

Before exchange specification documents are tagged in GitHub and put online at http://schemas.usgin.org/models, the following checks should be made:
• Field headings are consistent in spelling, capitalization, and order in all tabs of the Excel workbook (Data and FieldList tabs).
• Field headings spelling, capitalization, order, and cardinality are exactly the same in the Excel workbook (as described in the FieldList tab) and in the schema (XSD).
• The schema (XSD) has the first field as “OBEJCTID”.
• The schema (XSD) has the last field as “Shape”. Where both “ShapeLength” and “Shape” fields are used, “ShapeLength” is second to last, and “Shape” is the last field. [xs:any, ShapeArea]

Repository management

A good first step is to download the GitHub GUI at https://github.com/ where you will click “Set up Git” and follow the steps. Be sure to always create a “readme.md” file to explain the purpose of the information exchange, indicate the content in the given repository, and provide any updates regarding the version in use or other pertinent information.

Create a new repository by going to the USGIN GitHub site at https://github.com/usgin-models and logging into GitHub. Next to the user name in the upper right-hand corner, click “+” and choose “New repository”. Once created, click the “Clone in Desktop” button in the repository to get a local copy and begin entering documents into your local folder. Once ready to push the changes to the “master” to be viewed by others, commit the changes and “sync” in the GUI. Edit existing content models in much the same way; clone the repository in your desktop then edit and sync your changes back to the master branch.

Naming conventions
The name of the schema (XSD) and Excel (XLS) representations of the information exchange, as well as the name of the content model repository, should be identical and reflect the exact name of the eventual service. See https://github.com/ngds/documents/wiki/NGDS-Tier-3-Service-Names,-Layer-Names,-and-URI-tokens for current content model service and layer names.

Creating a new version (editing an existing content model)

To propose a new version of an existing content model, that is, to make edits to an existing content model for use in the system at-large, a user begins at the existing repository for a given content model at https://github.com/usgin-models. Any member of working group or interested party making edits to content model will need appropriate privileges from the steward of the main repository to 'push' changes to the master branch for the community to view. The following steps assume that the user does not have privileges to edit a given repository; in this case, the user will make edits locally then request that the repository steward accept the changes. Before going through the following steps, go to https://github.com/ and create an account.

1. Search through the list at https://github.com/usgin-models and click on the content model of interest. From this repository, two actions are needed; 'fork' your own copy of the repository (step 2), then 'clone' that repository to your Desktop (step 3).
2. From the repository page of interest (i.e., https://github.com/usgin-models/FluidFluxInjectionDisposal) locate and click the "Fork" button in the upper-right. This will give you an independent space to make edits to the content model in that repository, without permissions needed from the main repository.
   a. When you have your own repository fork page, locate the "branch:master" drop-down and click. Enter text into this space to name your own branch (your own version of the contents in the repository).
3. Clone it to your desktop computer; find the "Clone to Desktop" button at the lower-right of the page. This will allow access to and editing of all the files in the repository, but to manage those files, a GitHub GUI (Graphical User Interface) is needed.
   GitHub GUI for Windows
   a. Go to https://github.com/
   b. Click on ‘Set up Git’ in the far left box.
   c. Click on the green ‘Download GitHub for Windows’
   d. This will download a GUI where the user can set up a Desktop location for the files. In the local folder of cloned files (on your specified Desktop location), open and edit the files.
4. In the downloaded GUI for Windows, click the arrow to open the repository in which you've been working. To make your changes appear on the GitHub site, you will 'commit' then 'sync';
   a. Click 'Uncommitted Changes' to enter a statement about your changes and click 'Commit to master'.
   b. Click the 'sync' button in the upper-right.
5. In this last step, the user will request the repository steward to accept the new changes by making a Pull Request.
   a. In your new forked repository, click the green button to the left of 'branch:{your fork name}' (hovering over the button will provide a pop-up text which reads "Compare, review, create a pull request").
   b. This will take you to the compare/{your fork name} page; Click the green 'Create Pull Request' button.
   c. In this next page, you will type in a title description for your changes, then click the green 'Send pull request' button. The steward of the main repository can then respond and accept your changes.
   Steward Responsibility:
6. Notifications regarding changes in the content model must be posted at https://github.com/ngds/service-notifications/issues to be read by the RSS feed at http://notifications.usgin.org/. This issue must indicate reasons for the change and a reasonable comment period.
7. Comments and edits continue in the GitHub repository (possibly repeating steps 1-5).
8. Following approval by the working group and the steward, a new version of the content model is indicated on the “About” tab of the content model Excel file and tagged in the GitHub repository, rendering the previous version of the content model deprecated.
9. The new version of the content model is then uploaded by an administrator at http://schemas.usgin.org/models/ to be made available to the public.

Contact the steward (repository owner) directly
You can contact any GitHub user by going to her/his user page. The last person to have made a commit in the repository of interest (likely the steward) will be listed with their personal icon on the repository page just below the 'branch:' drop-down button. Click on the user name, where you will be taken to that user's page. The contact information, including email address, is given if authorized by that user.