Skip to content

Latest commit

 

History

History
384 lines (296 loc) · 17 KB

CONTRIBUTING.md

File metadata and controls

384 lines (296 loc) · 17 KB

xAPI-Spec

Contributors

Message To Contributors

"My thanks to everyone who contributed to the Experience API project. Many of you have called into the weekly meetings and helped to shape the specification into something that is useful for the entire distributed learning community. Many of you assisted in releasing code samples, products, and documentation to aid those who are creating and adopting the specification. I'd also like to thank all of those who were involved in supplying useful, honest information about your organization's use of SCORM and other learning best practices. Through the use-cases, shared experiences, and knowledge you have shared, ADL and the community clearly identified the first step in creating the Training and Learning Architecture--the Experience API. You are truly the community leaders on which we depend to make our training and education the very best."

Kristy S. Murray, Ed.D.

Director, ADL Initiative

Working Group Contributors

Name Organization
Aaron Silvers ADL
Al Bejcek NetDimensions
Ali Shahrazad SaLTBOX
Andrew Downes Watershed
Andriy Drozdyuk
Andy Johnson ADL
Andy Whitaker Watershed
Ángel Serrano eUCM
Anthony Altieri American Red Cross
Anto Valan Omnivera Learning Solutions
Avron Barr Aldo Ventures, Inc.
Ben Clark Rustici Software
Bill McDonald Boeing
Brian J. Miller Rustici Software
Chad Udell Float Mobile Learning
Chaim-Leib Halbert Rustici Software
Chris Handorf Pearson
Chris Sawwa Meridian Knowledge Solutions
Dan Allen Litmos
Dan Kuemmel Sentry Insurance
Danny Pham
Dave Mozealous Articulate
David Ells Rustici Software
David N. Johnson Clear Learning Systems
David Pate Riptide Software
Dennis Hall Learning Templates
Doug Hagy Twin Lakes Consulting Corporation
Eric Johnson Planning and Learning Technologies, Inc.
Fiona Leteney Feenix e-learning
Greg Tatka Menco Social Learning
Ingo Dahn University Koblenz-Landau
Jason Haag ADL
Jason Lewis Yet Analytics
Jeff Place Questionmark
Jennifer Cameron Sencia Corporate Web Solutions
Jeremy Brockman
Jhorlin De Armas Riptide Software
Joe Gorup CourseAvenue
Joerg Boeselt Brightcookie
John Kleeman Questionmark
Jonathan Archibald Brightwave
Jonathan Poltrack ADL
Kris Miller edcetra Training
Kris Rockwell Hybrid Learning Systems
Lang Holloman
Lewis Cowper
Loic Jeannin CrossKnowledge
Lou Wolford ADL
Luke Hickey dominKnow
Marcus Birtwhistle ADL
Mark Davis Exambuilder
Matteo Scaramuccia
Megan Bowe Rustici Software
Melanie VanHorn ADL
Michael Flores Here Everything's Better
Michael Roberts vTrainingRoom
Michael Wheeler
Mike Palmer OnPoint Digital
Mike Rustici Watershed
Nick Washburn Riptide Software
Nikolaus Hruska ADL
Pankaj Agrawal Next Software Solutions
Patrick Kedziora Kedzoh
Paul Esch Nine Set
Paul Roberts Questionmark
Rich Chetwynd Litmos
Richard Fouchaux Ontario Human Rights Commission
Richard Lenz Organizational Strategies, Inc.
Rick Raymer
RJ Zaworski
Rob Chadwick ADL
Robert Lowe NetDimensions
Roger Swetnam
Russell Duhon SaLTBOX
Ryan Smith HT2
Stephen Trevorrow Problem Solutions, LLC.
Steve Baumgartner
Steve Flowers XPConcept
Thomas Ho
Tim Martin Rustici Software
Tom Creighton ADL
Tyler Mulligan ADL
Walt Grata ADL
Yannick Warnier Chamilo
Zach Lowry Watershed

Historical Contributors

In collection of requirements for the Experience API, many people and organizations provided invaluable feedback to the SCORM, distributed learning efforts, and learning technology efforts in general. While not an exhaustive listing, the white papers gathered in 2008 by the Learning Education and Training Standards Interoperability (LETSI) group, the Rustici Software UserVoice website, one-on-one interviews and various blogs were important sources from which requirements were gathered for the Experience API specification.

ADL's Role in the Experience API

The Advanced Distributed Learning (ADL) Initiative has taken on the roles of steward and facilitator in the development of the Experience API. The Experience API is seen as one piece of the ADL Total Learning Architecture (previously the Training and Learning Architecture), which facilitates learning anytime and anywhere. ADL views the Experience API as an evolved version of Sharable Content Object Reference Model (SCORM) that can support similar use cases, but can also support many of the use cases gathered by ADL and submitted by those involved in distributed learning that SCORM could not enable.

How to Contribute

This document outlines various ways of contributing to the specification:

Review a Pull Request (PR)

The most helpful and easiest way to contribute to the specification is to review an existing PR. You can find a list of open PRs here. To review a PR you should:

  • Read any issues linked to from the PR description and make sure you understand the issue the PR is designed to address.
  • Read any comments on both the issues and the PR to understand if the goals of the original issue have changed and if any solutions have been agreed.
  • Read the relevant sections in the development version of the specification.
  • Check the 'Files changed' tab of the PR and look at what has changed. Use the 'rich diff' option if that helps you to see the changes better. Check to see if what's been changed matches the solution you expected from reading the issue and comments.
  • Look for problems such as typos, unintended changes to behaviour and any text that's unclear.
  • Check that anything that's been removed has either been replaced or the removal was intentional (based on reading the issue and comments).
  • Check that the Style Guide has been followed.
  • If you spot any issues with the PR, add a comment describing these problems as best you can and suggesting how they can be resolved.
  • If the PR looks good to you, add a comment saying "+1".
  • If you are unsure about the PR or have questions, ask questions in the PR comments.
  • If you feel that the PR should never be merged, even with changes, add a comment starting with "-1" and explaining your reasons. If your comments run contrary to what's already been agreed in the issues, there might be some resistance, but that's ok if you have a strong argument!

When reviewing a PR please don't:

  • Review and leave no comment; always let us know you've had a look!
  • Suggest additional changes outside of what the PR was intended to achieve. Raise a separate issue for additional changes.
  • Make vague criticisms without suggesting the changes to the PR that would meet those criticisms.

Suggest a solution

The second most helpful and second easiest way to contribute to the specification is to suggest a solution to an issue that has been raised. Ideally the person who raises the issue will propose a solution, but this does not always happen and you may be able to improve a suggestion.

To suggest a solution to an issue you should:

  • Read the issue and ensure you understand the problem being described. Ask questions if you need to.
  • Read the relevant sections in the development version of the specification.
  • Add a comment stating:
    • Which sections of the specification you propose to change.
    • A description of the proposed change.
    • Any reasons for and against the change you're proposing.

Once your suggestion has been discussed and agreed, add another comment summarising your understanding of the outcome of the discussion and including proposed wording for the changes you've suggested.

Good and detailed suggested solutions for issues make it much easier to write PRa and helps to ensure those PRs are merged faster.

Make a Pull Request (PR)

The hardest way of directly contributing to the specification is to make Pull Requests and the xAPI Working Group recommends only getting involved in this way if you are already used to Github and markdown and/or have previously contributed to reviewing PRs and suggesting solutions to issues.

Before making a PR you should:

  • Read the issue you are planning to address carefully including any comments.
  • Read the relevant sections in the development version of the specification.
  • Read any suggested solutions to the issue and the discussion around those issues.

If you would like to raise a PR that directly addresses your own concern, there is no need to raise a separate issue.

To make a PR you will need to edit the appropriate .md file either using the GitHub.com interface, or use git on your local computer. The GitHub.com interface is simpler for new users and is ideal for smaller changes like typos. These two methods are described below.

When making a PR, you should include a description that explains:

  • What issue numbers of any issues you are addressing (normally just one issue)?
  • How does your PR relate to any proposed solutions to the issue?
  • If you have moved sections, have you made any changes to content within those moved sections?
  • What decisions did you make in writing the change? Why did you make those decisions?

Edit on GitHub.com

To edit the specification on GitHub.com, first open the development version of the specification, then follow the instructions here.

Edit Locally

Set up

If you are not currently working with GitHub and git, follow these set up steps first. GitHub provides excellent help at https://help.github.com/articles/set-up-git

Fork the ADL repository

Go to the Experience API repository. Fork the repository to your own account using the "Fork" button on the top right of Experience API repository page. This makes a copy of the Experience API repository. This fork gives you the ability to edit your version of the document without impacting the master copy.

Install Git (use cmd line) or Install Windows/Mac GitHub client

You need to install Git to work with a GitHub repository. If you are on a Windows machine, you can download the GitHub client app. If you use a Mac you can download the GitHub client app but will also have to download git to add a remote to the master repository. Otherwise install git from the git site.

Git This provides a command line client app for working with a git repository (like GitHub) Download and run git install

GitHub Client GitHub Client provides a GUI interface to simplify working with a repository on GitHub. This does not currently support synchronizing with a master repository so some commands will still need to be completed using the command line.

Mac: http://mac.github.com/ Windows: http://windows.github.com/

Clone your GitHub fork to your machine

To make edits and work on the files in the repository, clone your repository to your local machine using Git. The url is provided on the home page of your repository (ex. https://github.com/<your username>/xAPI-Spec/)

Git git clone https://github.com/<your username>/xAPI-Spec/>

GitHub Client On the home screen of the client app, select your account under 'github' and choose the repository you want to clone. Selecting the repository from the list gives you an option to clone it.

Add ADL repository as upstream remote

Add a remote repository to git to reference the master repository. This will make synchronizing with the master repository a bit easier.

Git git remote add upstream https://github.com/adlnet/xAPI-Spec

GitHub Client Currently the GitHub clients don't have a way to synchronize with the master repository. In order to do this, open your repository on the GitHub client app home screen. On the repository screen select 'tools' and 'open a shell here'. Alternatively use the 'Git Shell' shortcut if it was created during installation. NOTE: If you're using a Mac there is no shell shortcut so navigate to /your/repo/path/xAPI-Spec then follow the shell instructions.

In the shell, enter.. git remote add upstream https://github.com/adlnet/xAPI-Spec

Workflow

Sync up with ADL Repository development

Pull down changes from the development repository. This automatically does a fetch of the repository and a merge into your local repository. Currently the development version of the spec is 1.0.3.

Git and GitHub Client git pull upstream 1.0.3

Make Changes Locally

Edit the local copy of the file, save and commit. Rule of thumb: Use commits like save points. Commit to indicate logical groups of edits, and places where the edits could be safely rolled back.

Git git commit -a -m "<commit message>"

GitHub Client The GitHub client will detect saved changes to the documents in your local repository and present a button to commit your edits at the top right of the repository screen.

Push Changes to Your Repository (Origin)

Pushing your changes to your remote GitHub repository stages the files so that you can then make requests to the master repository to merge in your changes.

Git git push origin

GitHub Client The GitHub client has a 'sync' button at the top of the repository screen. This will synchronize your local and remote (origin) repository.

Submit a Pull Request to Master ADL Repository (Upstream)

When you forked from the Experience API repository, a link back to the master repository is remembered. To send your changes back the the master repository, click the "Pull Request" button at the top of your repository page. This will direct you to a page that gives you the ability to submit a request to the master repository to merge in the changes you committed.

Style Guide

Expected Values

If a specific data format and value are to be used, the code style should be used to denote this.

For example:

A list of item ids is delimited by `[,]`

And

The value returned must be `false`.

Property and object names

When referring to a property, parameter or object, but not specifically calling it out as property, parameter, or object the name should be capitalized. No formatting or quotes should be used.

For example:

Context Activities within the Context of the Statement are awesome.

When a specific type is called out, Double quotes should be used (e.g. properties, parameters, and objects). When used within quotes, the capitalization should match that actually used in the object being described.

For example:

You can use "category" Context Activities to denote the recipe being followed in crafting the statement.

And

The "member" property is an unordered list!

When a value is expected or described within plain text, but isn't specifically code, single quotes should be used. In situations where it is important to group text to be specific to the concept, single quotes should also be used. Single quotes are also allowable if the text would be unclear due to certain property names. Basically, single quotes are the catch-all for any case where not having any clarifying punctuation or style would cause confusion.

For example:

The reserved Verb 'http://adlnet.gov/expapi/verbs/voided' is an exception.

And

These additional properties are called ‘interaction component lists’

And

The Score Object SHOULD include 'scaled'

And

The 'binary' value should be used.

Headings

Hashes (#) should be used for all headings following the following format:

Experience API (1 hash)

1 Statement (2 hashes)

1.1 Top level property (3 hashes)

1.1.1 next level (4 hashes)

1.1.1.1 next level and any deeper levels (5 hashes)
Rationale, details etc. (6 hashes)