This document outlines various ways con contributing to the specification:
- Reviewing open Pull Requests
- Suggesting solutions to issues
- Making a Pull Request to address an issue
- Read any issues linked to from the PR description and make sure you understand the issue the PR is desigend 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 Stle 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 arguement!
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 critisisms without suggesting the changes to the PR that would meet those critisisms.
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 maake it much easier to write PRa and helps to ensure those PRs are merged faster.
# Make a Pull Request (PR) The hardest way of driectly 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 xAPI.md 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 writting the change? Why did you make those decisions?
To edit the specification on GitHub.com, first open the development version of the specification, then follow the instructions here.
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
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.
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/
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 a remote repository to git to reference the master repository. This will make synchronizing with the master respository 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
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
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.
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.
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 ValuesIf 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```.
When refering 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 un-ordered 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.
Hashes (#) should be used for all headings following the following format: