From: Greg Gay Date: Wed, 21 Sep 2011 21:19:39 +0000 (-0400) Subject: Update developer doc with GitHub information X-Git-Url: https://iam.tj/gitweb/gitweb.cgi?p=atutor.git;a=commitdiff_plain;h=183e371201b11264e2612bef59afbd6c95fc2d70 Update developer doc with GitHub information --- diff --git a/docs/documentation/developer/guidelines.html b/docs/documentation/developer/guidelines.html index cf3466c8b..a0cb906aa 100644 --- a/docs/documentation/developer/guidelines.html +++ b/docs/documentation/developer/guidelines.html @@ -86,12 +86,12 @@ pre.code { -
  • 4. Subversion (SVN) +
  • 4. GitHub Repository
  • 5. Communication
    • @@ -258,42 +258,71 @@ allow_url_fopen = On register_argc_argv = Off

    top -

    4. Subversion (SVN)

    -

    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 Subversion homepage.

    - -

    4.1 Installing an SVN Client & Checking-Out

    -

    To obtain a working copy of ATutor, you need to install an SVN client and do a checkout 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.

    - -

    For windows users, we recommend using TortoiseSVN, 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 checkout the ATutor source code. Right-click to pop-up the context menu and select the command "Checkout...".

    -

    For repository URL, enter http://svn.atutor.ca/repos/atutor/trunk/docs. 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.

    - -

    For non-Windows users, download an appropriate SVN package from the Subversion homepage 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: svn checkout http://svn.atutor.ca/repos/atutor/trunk/docs. Unix users also have available a GUI tool called RapidSVN

    -

    The checkout includes:

    - -

    Extra modules can also be checked out into the ATutor mods/ directory, from where they can be easily installed using the ATutor administor's Install Modules tool. See the ATutor Module Documentation for more about creating and modifying modules. From within the docs/mods/ directory of your development version of ATutor, use svn checkout http://svn.atutor.ca/repos/atutor/trunk/mods/[module_name].

    -

    4.2 Installing ATutor From SVN

    -

    Before starting the installation process you should create an empty `config.inc.php` file in the `include/` directory: use touch config.inc.php 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.

    - -

    4.3 Updating ATutor From SVN

    -

    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: svn update.

    - -

    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 atutor_upgrade_x.y.z_to_1.9.sql, where x.y.z is the version of the currently available stable release.

    - -

    4.4 Keywords

    -

    Until Subversion supports server wide configuration options, the svn:keyword="Id" 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 // $ I d (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 commit.

    +

    4. GitHub

    +

    The ATutor source code is maintained in a GitHub repository, 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 Git Pro, or review the GitHub Help documentaiton.

    + +

    4.1 Setting up a Git Development Environment

    +

    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.

    + +

    For Mac users there is GitHub for Mac, which can be installed to setup Git on your Mac. It provides a graphical client through which GitHub can be accessed.

    + +

    Windows users have a variety of GitHub clients available. A quick search will turn up many. One popular client for Windows is SmartGit. Another is Cygwin

    + +

    Linux users also have a variety of Github clients available, such as Git Cola or Giggle, 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 apt-get install git at the command prompt.

    + +

    4.2 Creating and Maintaining a Git Fork

    +

    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 GitHub account 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 "Fork" 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 [username]/ATutor, where [username] is your GitHub login.

    + +

    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:

    + +

    Create a clone
    + git clone git@github.com/username/ATutor.git (create a local copy, or clone, of the fork you created on GitHub)
    + cd ATutor (move into the cloned repository)
    + git remote add upstream git://github.com/atutor/ATutor.git ( for later fetching upstream changes from the main ATutor repository to keep your code current)

    + +

    Create a branch to work in
    -

    After the file has been added and committed to the repository the keyword will be expanded into // $Id: guidelines.html 3071 2005-01-12 21:53:13Z joel $. 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.

    + git checkout -b new_feature (to create a working branch and switch to that branch. give the branch a descriptive name.)
    + git branch (to list the branches)

    -

    To set svn:keyword="Id" on a file using TortoiseSVN, right-click on a file, select "Properties" then select the "TortoiseSVN" tab, enter svn:keywords in the drop-down and Id in the text box then use the "Set" button.

    + +

    Edit, create, add copies of file as you would during development +
    + git status (to list modified files)
    + git add [filename] (to stage modified file, or "git add *" to stage all modified files)
    + git status (to list staged files)
    + git commit -m "describe the changes in a log message" (to save the staged file to the new_feature branch you created above)
    + git log (to list changes that were committed)

    + +

    Keep your branch up-to-date (perform these operations often)
    + git checkout master (switch to the local master branch)
    + git pull upstream master (update your local master branch with code from the main ATutor repository)
    + git checkout new_feature (switch to the local new_feature branch)
    + git merge master (merge updates in the local master to your working branch, then resolve any conflicts)

    + +

    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 atutor_upgrade_x.y.z_to_1.9.sql, where x.y.z is the version of the currently available stable release.

    + +

    Submitting code for review and addition to ATutor
    + git push origin new_feature (push your new_feature branch to your own GitHub repository)
    + Go to https://github.com, login, then under "switch branches" select the new_feature branch you just pushed.
    + Click on the Pull Request button, to send your code for review.
    + Read through the pull request to ensure it is correct, for example + "You're asking atutor to pull [1] commit into atutor:master from username:new_feature"
    + Press Send pull request to finish your code submission.

    + +

    Clean up when you're done (after the code has been reviewed, accepted, and merged into the ATutor master branch)
    + git branch master (move into a branch other than the one to be deleted)
    + git branch -D new_feature (delete the branch from your local repository)
    + git push origin :new_feature (remove the branch from GitHub)

    +

    4.3 Installing from GitHub

    +

    Installing the development code cloned from GitHub requires one extra step in addition to the standard installation described in the Installation Instructions. Once the source code has been cloned, change to the ATutor/docs/include directory and create an empty configuration file by issuing the command touch config.inc.php, then run the installer as described in the instructions.

    + + top

    5. Communication

    -

    All communication between developers should occur in the Development Forum. Please try to keep discussions public including any feature proposals.

    +

    Much communication between developers occurs in the Development Forum. Please try to keep discussions public including any feature proposals. You may also communicate with directly through IRC. Using your IRC client, open irc://irc.oftc.net/ then join the #atutor channel.

    top

    6. Patches