diff --git a/README.md b/README.md index 854f9c9..424d1dc 100644 --- a/README.md +++ b/README.md @@ -67,3 +67,115 @@ There is a Readme for operating the Test Suite found at `C:\dev\SCORM-2004-4ed-T WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + +## Collaboration +For those wishing to contribute to the programming efforts of the SCORM 2004 4th +Edition Test Suite, please follow this process: + +### 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](https://help.github.com/articles/set-up-git) + +#### Sign up for a GitHub account +If you do not already have a GitHub account, [sign up](https://github.com/signup/free). + + +#### Fork the ADL repository +Go to the SCORM-2004-4ed-Test-Suite repository. Fork the repository to your own account using +the "Fork" button on the top right of SCORM-2004-4ed-Test-Suite repository page. This makes a +copy of the SCORM-2004-4ed-Test-Suite 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](http://git-scm.com/downloads) + +__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//xAPI-Spec/```) + +__Git__ +```git clone https://github.com//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 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``` + + +### Workflow + +#### Sync up with Master ADL Repository +Pull down changes from the master repository. This automatically does a +fetch of the master repository and a merge into your local repository. + +__Git and GitHub Client__ +```git pull upstream master``` + +#### 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 ""``` + +__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. + + +