<ul>\r
<li>3.1 <a href="#php-configuration">PHP Configuration</a></li>\r
</ul></li>\r
- <li>4. <a href="#subversion">Subversion (SVN)</a>\r
+ <li>4. <a href="#github">GitHub Repository</a>\r
<ul>\r
- <li>4.1 <a href="#svn-install">Installing an SVN Client & Checking-Out</a></li>\r
- <li>4.2 <a href="#svn-installing_atutor">Installing ATutor From SVN</a></li>\r
- <li>4.3 <a href="#svn-update">Updating ATutor From SVN</a></li>\r
- <li>4.4 <a href="#svn-keywords">Keywords</a></li>\r
+ <li>4.1 <a href="#github_setup">Setting up a Git Development Environment</a></li>\r
+ <li>4.2 <a href="#github_maintaining">Creating anfd Maintaining a Git Fork</a></li>\r
+ <li>4.3 <a href="#svn-install">Installing from GitHub</a></li>\r
+ \r
\r
</ul></li>\r
<li>5. <a href="#communication">Communication</a></li>\r
register_argc_argv = Off</pre></p>\r
\r
<a href="#top" class="top">top</a>\r
-<h2><a name="subversion"></a>4. Subversion (SVN)</h2>\r
- <p>We have adopted Subversion (SVN) in place of the aging CVS, allowing us to open up the development repository while still maintaining control over the core project. Additional information can be found on the <a href="http://subversion.tigris.org/project_packages.html">Subversion homepage</a>.</p>\r
-\r
- <h3><a name="svn-install"></a>4.1 Installing an SVN Client & Checking-Out</h3>\r
- <p>To obtain a working copy of ATutor, you need to install an SVN client and do a <kbd>checkout</kbd> from our repository of the latest ATutor source code. Checking out the repository creates a copy of it on your local machine with the necessary version control information. The location of the copied files should be web accessible, i.e. a directory under your web server's path. </p>\r
-\r
- <p>For windows users, we recommend using <a href="http://tortoisesvn.tigris.org/">TortoiseSVN</a>, which is a feature-rich SVN extension for Windows that supports many of the options of other SVN clients (file browser and filters not being one of them). Once TortoiseSVN has been successfully installed and you've rebooted your computer, go to a working directory where you wish to <kbd>checkout</kbd> the ATutor source code. Right-click to pop-up the context menu and select the command "Checkout...". </p>\r
\r
- <p>For repository URL, enter <kbd>http://svn.atutor.ca/repos/atutor/trunk/docs</kbd>. If you enter a folder name that does not yet exist, a directory with that name will be created. Press "OK", and the source will be downloaded to your computer.</p>\r
-\r
- <p>For non-Windows users, download an appropriate SVN package from the <a href="http://subversion.tigris.org/project_packages.html" title="Subversion packages">Subversion homepage</a> and follow the installation instructions. These packages use the command-line client. Checking out the most recent ATutor source code can be done with the following command: <kbd>svn checkout http://svn.atutor.ca/repos/atutor/trunk/docs</kbd>. Unix users also have available a GUI tool called <a href="http://rapidsvn.tigris.org/">RapidSVN</a></p>\r
- <p>The checkout includes:</p>\r
- <ul>\r
- <li><kbd>bundle.sh</kbd> - Execute this shell script to generate an installable bundle of the ATutor.</li>\r
- <li><kbd>docs/</kbd> - The ATutor source code</li>\r
- <li><kbd>mods/</kbd> - Extra module source code</li>\r
- </ul>\r
- <p>Extra modules can also be checked out into the ATutor <kbd>mods/</kbd> directory, from where they can be easily installed using the ATutor administor's Install Modules tool. See the <a href="modules.html">ATutor Module Documentation</a> for more about creating and modifying modules. From within the <kbd>docs/mods/</kbd> directory of your development version of ATutor, use <kbd>svn checkout http://svn.atutor.ca/repos/atutor/trunk/mods/[module_name]</kbd>.</p>\r
- <h3><a name="svn-installing_atutor"></a>4.2 Installing ATutor From SVN</h3>\r
- <p>Before starting the installation process you should create an empty <kbd>`config.inc.php`</kbd> file in the <kbd>`include/`</kbd> directory: use <kbd>touch config.inc.php</kbd> on UNIX. Browse to the location of your checked out files in a web browser and proceed with the ATutor installation instructions. This will set up the database and user accounts for your ATutor system. The resulting ATutor installation will be your development environment.</p>\r
-\r
- <h3><a name="svn-update"></a>4.3 Updating ATutor From SVN</h3>\r
- <p>You should regularly perform updates from the repository to make sure you are working with the developers' latest files. To do this with TortoiseSVN, right click on the working folder and select "Update" from the context menu. For command-line svn clients, use: <kbd>svn update</kbd>.</p>\r
-\r
- <p>Always review the latest SVN SQL upgrade file to ensure your database structure is up-to-date. The file will contain schema changes of the current pre-released source. Example: If the current working source will be version 1.9, then the upgrade file to keep track of will be named <kbd>atutor_upgrade_<em>x.y.z</em>_to_1.9.sql</kbd>, where <kbd><em>x.y.z</em></kbd> is the version of the currently available stable release.</p>\r
-\r
- <h3><a name="svn-keywords"></a>4.4 Keywords</h3>\r
- <p>Until Subversion supports server wide configuration options, the <kbd>svn:keyword="Id"</kbd> option will have to be set on a file-by-file basis via the client. After the keyword property has been set for the given file, add the line <kbd>// $ I d</kbd> (without the spaces) at the top of the file directly below the main comment block to identify the author, date and time of the last <kbd>commit</kbd>.</p>\r
+<h2><a name="github"></a>4. GitHub</h2>\r
+<p>The ATutor source code is maintained in a <a href="https://github.com/atutor/ATutor">GitHub repository</a>, a public version control system that provides "Social Coding" capabilities, making it relatively easy for ATutor developers to have work added to ATutor's public source code. Developers will need to become familiar with Git and GitHub if they wish to participate in ATutor development. There is plenty of documentation on using Git and GitHub. You might read through the book at <a href="http://progit.org/book/">Git Pro</a>, or review the <a href="http://help.github.com/">GitHub Help</a> documentaiton. </p>\r
+<a name="github_setup"></a>\r
+ <h3><a name="git-install"></a>4.1 Setting up a Git Development Environment</h3>\r
+ <p>Though there are a variety of Git client applications available, working from a command prompt issuing Git commands is relatively easy to learn. Knowing a small set of Git commands is all you required to get up and running, and contributing code through GitHub. </p>\r
+ \r
+ <p>For <strong>Mac users</strong> there is <a href="http://mac.github.com/">GitHub for Mac</a>, which can be installed to setup Git on your Mac. It provides a graphical client through which GitHub can be accessed.</p>\r
+ \r
+ <p><strong>Windows users</strong> have a variety of GitHub clients available. A quick search will turn up many. One popular client for Windows is <a href="http://www.syntevo.com/smartgit/index.html">SmartGit</a>. Another is <a href="http://www.cygwin.com/">Cygwin</a></p>\r
+ \r
+ <p><strong>Linux users</strong> also have a variety of Github clients available, such as <a href="http://cola.tuxfamily.org/">Git Cola </a> or <a href="http://live.gnome.org/giggle">Giggle</a>, among others. And, of course, if you prefer to just work from the command prompt, just install git itself. Most, probably all, Linux systems have a Git package available that can be installed through their package management system. On Ubuntu or Debian for instance, as the root user issue the command <kbd>apt-get install git</kbd> at the command prompt.</p>\r
+ \r
+<h3><a name="github_maintaining"></a>4.2 Creating and Maintaining a Git Fork</h3>\r
+ <p>All developers outside the core development team will work in their own fork of the ATutor source code located on GitHub. Creating a fork is pretty straight forward. Once your <a href="https://github.com/plans">GitHub account</a> is setup, and you have logged in, search for the atutor/ATutor repository. At the top of the screen while viewing the repository, click on the <kdb>"Fork"<kdb> button to create a fork of the master source code. You will now have a copy of the source code linked to your account, something like <kdb>[username]/ATutor</kdb>, where [username] is your GitHub login.</p>\r
+ \r
+ <p>Now you will want to clone the fork you created into your local development environment. Using your Git client you can then find its "clone" features to generate a local copy, or at the command prompt issue the following commands:</p>\r
+ \r
+ <p><strong>Create a clone</strong><br />\r
+ <kbd>git clone git@github.com/username/ATutor.git </kbd> (create a local copy, or clone, of the fork you created on GitHub)<br />\r
+ <kbd>cd ATutor </kbd> (move into the cloned repository)<br/>\r
+ <kbd>git remote add upstream git://github.com/atutor/ATutor.git</kbd> ( for later fetching upstream changes from the main ATutor repository to keep your code current)<br /></p>\r
+ \r
+ <p><strong>Create a branch to work in</strong><br />\r
\r
- <p>After the file has been added and committed to the repository the keyword will be expanded into <kbd>// $Id: guidelines.html 3071 2005-01-12 21:53:13Z joel $</kbd>. It is helpful to read that line when first opening a file as it lets you know if you were the last person to edit that file and if not, to look out for possible changes.</p>\r
+ <kbd>git checkout -b new_feature </kbd> (to create a working branch and switch to that branch. give the branch a descriptive name.)<br />\r
+ <kbd>git branch </kbd> (to list the branches)<br /></p>\r
\r
- <p>To set <kbd>svn:keyword="Id"</kbd> on a file using TortoiseSVN, right-click on a file, select "Properties" then select the "TortoiseSVN" tab, enter <kbd>svn:keywords</kbd> in the drop-down and <kbd>Id</kbd> in the text box then use the "Set" button.</p>\r
\r
+ \r
+ <p><strong>Edit, create, add copies of file as you would during development</strong>\r
+ <br />\r
+ <kbd>git status </kbd> (to list modified files)<br />\r
+ <kbd>git add [filename] </kbd> (to stage modified file, or "git add *" to stage all modified files)<br />\r
+ <kbd>git status </kbd> (to list staged files)<br />\r
+ <kbd>git commit -m "describe the changes in a log message"</kbd> (to save the staged file to the new_feature branch you created above)<br />\r
+ <kbd>git log </kbd> (to list changes that were committed)<br /></p>\r
+ \r
+ <p><strong>Keep your branch up-to-date</strong> (perform these operations often)<br />\r
+ <kbd>git checkout master </kbd> (switch to the local master branch)<br />\r
+ <kbd>git pull upstream master </kbd> (update your local master branch with code from the main ATutor repository)<br />\r
+ <kbd>git checkout new_feature </kbd> (switch to the local new_feature branch)<br />\r
+ <kbd>git merge master </kbd> (merge updates in the local master to your working branch, then resolve any conflicts)<br /></p>\r
+ \r
+ <p>After pulling from the ATutor master repository, review the latest SQL upgrade file to ensure your database structure is up-to-date (in the install/db/ directory ). The file will contain schema changes of the current pre-released source. Example: If the current working source will be version 1.9, then the upgrade file to keep track of will be named <kbd>atutor_upgrade_<em>x.y.z</em>_to_1.9.sql</kbd>, where <kbd><em>x.y.z</em></kbd> is the version of the currently available stable release.</p>\r
+ \r
+ <p><strong>Submitting code for review and addition to ATutor</strong> <br />\r
+ <kbd>git push origin new_feature </kbd> (push your new_feature branch to your own GitHub repository)<br />\r
+ Go to <a href="https://github.com">https://github.com</a>, login, then under "switch branches" select the <kbd>new_feature</kbd> branch you just pushed.<br />\r
+ Click on the <strong>Pull Request</strong> button, to send your code for review.<br />\r
+ Read through the pull request to ensure it is correct, for example \r
+ "<em>You're asking atutor to pull [1] commit into atutor:master from username:new_feature</em>" <br/>\r
+ Press <strong>Send pull request</strong> to finish your code submission.</p>\r
+\r
+ <p><strong>Clean up when you're done</strong> (after the code has been reviewed, accepted, and merged into the ATutor master branch)<br /> \r
+ <kbd>git branch master</kbd> (move into a branch other than the one to be deleted)<br />\r
+ <kbd>git branch -D new_feature</kbd> (delete the branch from your local repository)<br />\r
+ <kbd>git push origin :new_feature</kbd> (remove the branch from GitHub)</p>\r
+<h3><a name="svn-install"></a>4.3 Installing from GitHub</h3>\r
+ <p>Installing the development code cloned from GitHub requires one extra step in addition to the standard installation described in the <a href="http://atutor.ca/atutor/docs/installation.php#fresh">Installation Instructions</a>. Once the source code has been cloned, change to the ATutor/docs/include directory and create an empty configuration file by issuing the command <kbd>touch config.inc.php</kbd>, then run the installer as described in the instructions.</p>\r
+ \r
+ \r
<a href="#top" class="top">top</a>\r
<h2><a name="communication"></a>5. Communication</h2>\r
- <p>All communication between developers should occur in the <a href="http://atutor.ca/forum/12/1.html">Development Forum</a>. Please try to keep discussions public including any feature proposals.</p>\r
+ <p>Much communication between developers occurs in the <a href="http://atutor.ca/forum/12/1.html">Development Forum</a>. Please try to keep discussions public including any feature proposals. You may also communicate with directly through IRC. Using your IRC client, open <kbd>irc://irc.oftc.net/</kbd> then join the #atutor channel. </p>\r
\r
<a href="#top" class="top">top</a>\r
<h2><a name="patches"></a>6. Patches</h2>\r
projects / atutor.git / commitdiff