Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README.md: syntax highlighting, link, typo/format updates #4

Merged
merged 1 commit into from
Mar 6, 2013
Merged

README.md: syntax highlighting, link, typo/format updates #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 87 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,137 @@
<img src="http://aicc.org/joomla/dev/images/aicc-logo.png"> CMI-5 Current Working Draft
---

*Contact cmi5@aicc.org if you have questions about this specification*<br>
*Contact <cmi5@aicc.org> if you have questions about this specification*<br>
*By using this repository you are agree to the terms of the license agreement defined in license.txt*<br>
*Note that this is a working draft and is NOT intended for implementation.*<br>




# 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 <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 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:__ <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>/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/<your username>/CMI-5_Spec_Current/```)

__Git__
```git
git clone https://github.com/<your username>/CMI-5_Spec_Current/
```

__Git__
```git clone https://github.com/<your username>/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 "<commit message>"```
__Git__
```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.
__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.