Skip to content

Latest commit

 

History

History
151 lines (101 loc) · 8.68 KB

CONTRIBUTE.md

File metadata and controls

151 lines (101 loc) · 8.68 KB
Raw

Maintenance of generated files

To keep some website technology-stack elements from interfering with one another, some files are generated by scripts. A top-level Makefile handles maintenance of these folders.

Before submitting a pull request, the results of these three calls from the repository root directory should be visually confirmed with git status and/or git diff:

make clean
make
make check

That is, a fresh repository clone should not see any output of git diff after running those three commands.

Narratives

If you have a JSON-LD narrative to edit or contribute, please review this section's directions.

The CASE website makes some trades from ease of development for the sake of presentation with static, version-controlled files. make is used to compile HTML and aggregated JSON files from source files. This is because the narrative pages are backed by JSON snippets, as inline data samples, and as functional JSON-LD data. Each narrative has a file named after its directory's basename, e.g. urgent_evidence.json; this file is also backed by those JSON snippets. Further, that composite JSON-LD file also backs queries that support the README.

To edit a narrative's index.html, don't edit index.html, because that file is generated; instead, edit index.html.in (e.g. here is the Urgent Evidence's template index.html.in file). Likewise for the compiled JSON file: Instead, a source file should be edited. After editing, make should be run to build all the "Downstream" affected files.

Before working with narratives

First, the workflow in this file only supports a local workflow, and does not support editing via Github's interactive web interface.

To start the editing process:

  • Use Git to clone the website repository.
  • Change directory to the cloned directory.
  • Run make check. Resources will download, some code will build, and unit tests will run. Administrator privileges will not be necessary. make -j will run this first step in parallel.

After running make check, you will have confirmed you are starting from a functioning state with tests passing.

Editing existing narratives

Each narrative has its housing directory with the user-friendly URL (e.g. examples/urgent_evidence, corresponding with https://caseontology.org/examples/urgent_evidence/). Each narrative also has its own source directory, where unit test code and JSON-LD snippets are stored.

To revise a narrative, modify files in its src/ directory. Take for example Urgent Evidence's src/ directory.

  • index.html.in - This is a template file housing the narrative text and data insertion points. It is the basis for generating index.html. It uses Automake-style substitution patterns (i.e. @STRING_TO_REPLACE@), executed in the shared Makefile's target generated-index.html.
  • @ strings in index.html.in rely on a name scheme for patterns to be substituted. They are expected to be file names of other files in the src/ directory, with alphabetic characters converted to uppercase, and all non-alphanumeric characters converted to underscores.
  • $(example_name)_base.json - The initial "snippet" JSON file, used to start the combined JSON-LD graph.
  • $(example_name)-*.json - follow-on snippet JSON files. (The Urgent Evidence narrative happens to not have any.)
  • query-*.sparql - Query files.

After committing changes to any of the files in the src/ directory, run make. If a Git-tracked file differs from a state that is freshly computed, a prompt will be given to review a diff output. If the diff looks like it contains expected changes, a cp command is provided in the last make output line starting UPDATE:.

The changes will be copied into place when make is run again in any directory above src/. When all looks ready, run git commit to make your patch.

Before posting your patch for a Pull Request, run make check from the top directory. Any generated changes not yet committed will raise a friendly error to encourage you to commit the revisions.

Adding JSON snippets or queries

Following the name scheme $(example_name)-*.json and query-*.sparql and the "upper-case, under-score" substitution pattern in index.html.in will be sufficient to add a new JSON-LD snippet or SPARQL query.

Adding a new narrative

The procedure for adding a new narrative that will have JSON-LD snippets follows the procedure for editing an existing narrative, though with two additional setup steps:

  • The new narrative should have a Makefile copied from any sibling narrative-directory, and likewise for the new narrative's src/ directory. Note the two Makefiles are written in a bare, "Pass-through" manner to call a more complex shared Makefile.
  • A short Python script should be written to combine the snippets and base JSON files into the combined JSON-LD graph file. (This step may be handled by a generic program in the future.) See e.g. the combiners for Asgard and Owl Trafficking.

CASE conformance

Note that to assure example base functionality, we expect each narrative to have its own JSON-LD passing through Continuous Integration. Continuous Integration calls case_validate to review data for conformance against the most recent published CASE version. The --allow-infos flags permits "Info"-severity non-conformance issues (such as UCO individual IRIs ending without a UUID), but fails a conformance check on encountering a "Warning"-level or higher severity. That is, the examples currently in this repository are all CASE-conformant, and ongoing testing requires new examples are also CASE conformant.

The Cyber Domain Ontology welcomes any questions about ontology-conformance issues on the respective issue tracker:

Handling draft ontology concepts

Some narratives incorporate concepts that are not yet part of CASE or UCO, but may be under proposal. These are housed in "Draft" ontology files, drafting.ttl, within the narrative directory. To support CASE workflow tracking, please keep all defined concepts within these drafting.ttl files synchronized with change proposal Jira tickets, linked with rdfs:seeAlso.

Testing website edits locally

The following script can take a fresh Ubuntu VM and get a local copy of the website running. The bundle exec call at the end reports the URL to use, typically http://localhost:4000/.

#!/bin/bash

# This software was developed at the National Institute of Standards
# and Technology by employees of the Federal Government in the course
# of their official duties. Pursuant to title 17 Section 105 of the
# United States Code this software is not subject to copyright
# protection and is in the public domain. NIST assumes no
# responsibility whatsoever for its use by other parties, and makes
# no guarantees, expressed or implied, about its quality,
# reliability, or any other characteristic.
#
# We would appreciate acknowledgement if the software is used.

# This script will clone the CASE website repository under ~/local/src,
# if not already cloned there, and execute a local Jekyll build of the
# website for testing in a browser.
# This script has been tested in an Ubuntu environment.

set -x
set -e
set -u

# Guarantee website-essential packages installed.
# dpkg tip for confirming package installation via:
#   https://stackoverflow.com/a/1298103
run_install=no
dpkg -s git \
  || run_install=yes
dpkg -s jekyll \
  || run_install=yes
dpkg -s zlib1g-dev \
  || run_install=yes
if [ "xyes" == "x${run_install}" ]; then
  sudo apt install \
    --yes \
    git \
    jekyll \
    zlib1g-dev
fi

mkdir -p ${HOME}/local/src
pushd ${HOME}/local/src
  if [ ! -d casework.github.io ]; then
    git clone \
      https://github.com/casework/casework.github.io.git
  fi

  pushd casework.github.io
    bundle --version \
      || sudo gem install bundler:2.0.2

    bundle install \
      --path vendor/bundle

    # Serve built website.
    # Via:
    #   https://help.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll
    bundle exec jekyll serve
  popd #casework.github.io
popd #${HOME}/local/src