Skip to content

Contributing

Jump to bottom
Will Hoyt edited this page Sep 18, 2019 · 3 revisions

Welcome to the Project DAVE contributing wiki page!

First off, thank you for stopping by. We appreciate your interest in the project and hope that this page will provide all the necessary information for getting started with contributing to the project.

Some of the following links point to the Primitives Document branch and will be updated to point at Master once the branch has been merged in

Background

DAVE is all about creating a link between learning questions, the algorithm which may answer them, and data visualizations which best display what the algorithms return.

The previous template is structured like this:

  • Section Title: Learning Question
  • Statement Requirements
  • LRS query to get Input Statements
  • Statement Parameters to Utilize
  • Algorithm: Summary
  • Algorithm: Formal Specification
  • Algorithm: Pseudocode
  • JSON schema for the Return Value of the Algorithm
  • Visualization: Description
  • Visualization: Prototype
  • Prototype Improvements

This structure is currently being refactored (as of 9/18/2018) around the new way of defining Algorithms in terms of Operations and Primitives. An introduction to this new set of definitions can be found here and is structured like this:

  • Terminology
  • Operation
  • Primitive
  • Algorithm
    • Initialization
    • Relevant?
    • Accept?
    • Step
    • Result

For an example of this new style with respect to

The introduction and examples above are undergoing a visual update because they currently feature text with in-line LateX and do not feature any formal definitions written in Z. The creation of Z schemas from the in-line LaTeX is an ongoing effort across Algorithm Definitions, Operation Definitions and Primitive Definitions (as of 9/18/2019).

Both the previous template and current draft template rely on a formal definition of xAPI Statements which should be read prior to contribution.

What Can I Work On?

There is a list of existing learning questions here but it is also possible to submit new learning questions, see below for more info. Within a learning question, you can work on any of the sections listed in the Background section.

Future iterations of DAVE will include example implementations of the algorithms in various coding languages. You may submit algorithm implementations for existing learning questions but please do not submit a new algorithm implementation alone. Instead, submit a new learning question with the algorithm implementation; for more information, see Submitting New Learning Questions section below.

Where Should I Work?

At the top level of the repo, there should be a directory for each learning question. If there isn't, you should make one named after the learning question. Within that directory, there should be these subdirectories

  • implementation
  • documentation
  • visualization

This structure is not currently found in the Dave repository (9/18/2019) but is the target format of the repository. Please follow this convention when contributing to Dave.

When contributing to Dave, please follow the GitHub flow and create a new branch for committing new changes. See the Workflow section below for more information.

Implementation

Implementation is for algorithm implementations in various languages. Each implementation should contain a working, runnable algorithm and associated tests.

Documentation

Documentation is for material which describes the algorithm. Material should cover one or more of the template sections:

  • Legacy
    • Statement requirements
    • LRS query to get input statements
    • Statement Parameters to Utilize
    • Algorithm summary
    • Algorithm formal specification
    • Algorithm pseudocode
    • JSON schema for the return value of the algorithm
  • Revised
    • Operations
    • Primitives
    • Algorithm
      • Initialization
      • Relevant?
      • Accept?
      • Step
      • Result

Many of the Legacy sections will be ported to the Revised format but the exact list of sections has not yet been determined (as of 9/18/2019).

The material does not have to be written in Latex, any text format will do.

Visualization

Visualization is for material which relates to the visualization of the algorithms output. Things in this directory may include mockups, improvement suggestions, etc.

Submitting New Learning Questions

To submit a new learning question, open a new issue where the title is the name of the learning question. Please include a description of the learning question, a rationale, and any other information you feel is relevant.

Workflow

  1. pick an existing learning question or create an issue for a new one
  2. search for an existing branch for the learning question or make a new branch
  3. find or create the top level algorithm directory and subdirectories (implementation, documentation and visualization)
  4. commit/save your work to the appropriate subdirectory
  5. when a learning algorithm is complete, submit the branch for a PR

When the review process is complete, the content will be merged into the master document.

Clone this wiki locally