diff --git a/README.md b/README.md index 4a44e11..ebc4c9a 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,137 @@ CMI-5 Current Working Draft --- -*Contact cmi5@aicc.org if you have questions about this specification*
+*Contact if you have questions about this specification*
*By using this repository you are agree to the terms of the license agreement defined in license.txt*
*Note that this is a working draft and is NOT intended for implementation.*
- - # Workflow for Editing the CMI-5 Specification ---- ## 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) +If you are not currently working with GitHub and git, follow these set up steps +first. GitHub provides excellent help at ### Sign up for a GitHub account If you do not already have a GitHub account, [sign up](https://github.com/signup/free). ### Fork the CMI-5 repository -Go to the CMI-5 repository. Fork the repository to your own account using -the "Fork" button on the top right of CMI-5 repository page. This makes a -copy of the CMI-5 repository. This fork gives you the ability to edit your +Go to the CMI-5 repository. Fork the repository to your own account using +the "Fork" button on the top right of CMI-5 repository page. This makes a +copy of the CMI-5 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. +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__ -__Git__ -This provides a command line client app for working with a git repository (like -GitHub) +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. +__GitHub Client__ -__Mac:__ http://mac.github.com/ -__Windows:__ http://windows.github.com/ +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:__ ++ __Windows:__ ### 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//CMI-5_Spec_Current/```) +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//CMI-5_Spec_Current/```) + +__Git__ +```git +git clone https://github.com//CMI-5_Spec_Current/ +``` -__Git__ -```git clone https://github.com//CMI-5_Spec_Current/>``` +__GitHub Client__ -__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. +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 CMI-5 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. +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/AICC/CMI-5_Spec_Current``` +__Git__ -__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/CMI-5_Spec_Current ``` then follow the shell instructions. - -In the shell, enter.. -```git remote add upstream https://github.com/AICC/CMI-5_Spec_Current ``` +```git +git remote add upstream https://github.com/AICC/CMI-5_Spec_Current +``` + +__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 +```shell +/your/repo/path/CMI-5_Spec_Current +``` +then follow the shell instructions. + +In the shell, enter.. +```git +git remote add upstream https://github.com/AICC/CMI-5_Spec_Current +``` ## Workflow ### Sync up with Master CMI-5 Repository -Pull down changes from the master repository. This automatically does a -fetch of the master repository and a merge into your local 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``` +__Git and GitHub Client__ +```git +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. +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 ""``` +__Git__ +```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. +__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. +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 +git push origin +``` -__Git__ -```git push origin``` +__GitHub Client__ -__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. +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 CMI-5 Repository (Upstream) -When you forked from the CMI-5 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. +When you forked from the CMI-5 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.