Difference between revisions of "Github"

Latest revision as of 12:54, 7 October 2021

References for GitHub and Git

For those who are ready for complete immersion into all things git -- here are several references.

Pro Git book http://progit.org/

(unreviewed at the moment -- YMVV)

http://gitref.org/ quick reference
https://help.github.com/articles/using-pull-requests
https://github.com/blog/966-improved-subversion-client-support
git cheat sheet: http://byte.kde.org/~zrusin/git/git-cheat-sheet-medium.png
Version Control by Example by Eric Sink which is available at http://www.ericsink.com/vcbe/
http://nvie.com/posts/a-successful-git-branching-model/ a potential workflow model for WeBWorK development -- we're still working on refining a workflow
see also Github Overview for more references

Difference between revisions of "Github"

Latest revision as of 12:54, 7 October 2021

Contents

Installation Manuals

WeBWorK software download

Github Overview

Quick instructions for updating WeBWorK to the GitHub version

References for GitHub and Git

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Documentation for

NAVIGATION

Tools

@@ Line 1: / Line 1: @@
-=== Github Overview ===
+===Installation Manuals===
-The current page provides instructions for quickly migrating from an SVN repository version of WeBWorK to the version hosted at Github.com.
-The page '''[[Github Overview]]''' provides a more conceptual description of git and Github.com.  It has instructions
+see [[:Category:Installation Manuals| Current Installation Manuals]]
-for using git and github as a developer as well as additional advanced tricks and shortcuts for keeping a WeBWorK installation
-up to date.
-=== Quick instructions for updating WeBWorK to the GitHub version ===
+=== WeBWorK software download ===
-* This description is primarily for those who are switching from versions of WeBWorK hosted on SVN (versions prior to 2.5) to those hosted on GitHub.
+WeBWorK online homework software is located at http://github.com/openwebwork.
-* Those who are already using version 2.6 and have downloaded the software from GitHub should consult the section on updating branches since the update instructions are shorter. If you already have files  /opt/webwork/webwork2/conf/site.conf and /opt/webwork/webwork2/conf/localOverrides.conf then it is likely that are already using software from the WeBWorK GitHub distributions.
+ webwork2 -- the instructor and user interface
-<div style="color:red">
+ pg       -- the macros for rendering questions
-* Your server will require at least perl version 5.10.x (5.12.x would be better, 5.18 is the current version) to run weBWorK release/2.7. Type   <code> perl --version </code> on the command line of your server to check.
+ webwork-open-problem-library  -- library of 35K+ homework questions
-</div>
-* You will need root access to the apache webserver via "sudo" in order follow the instructions below.
-*You will need to prepend "sudo" to many of the commands below in order to obtain the permissions needed to make these changes.
-==== Preserve current WW version and download software from GitHub ====
+=== Github Overview ===
-* We'll assume that our current webwork installation is located in the directory
+The page '''[[Github Overview]]''' provides a more conceptual description of git and Github.com.  It has instructions for using git and github as a developer as well as additional advanced tricks and shortcuts for keeping a WeBWorK installation up to date.
- /opt/webwork/
-with subdirectories
-  /opt/webwork/webwork2
-  /opt/webwork/pg
-  /opt/webwork/courses
-* For safety we will move the webwork2 and pg directories to "old" versions and create links that redirect pg and webwork2 to these renamed directories
-  cd /opt/webwork
-  mv webwork2 webwork2_old
-  mv pg pg_old
-  ln -s webwork2_old webwork2
-  ln -s pg_old pg
-* At this point our current webwork installation should exactly work as before.  Calls to webwork2 and pg are directed to the "old" (actually our current) versions  webwork2_old and pg_old. It's worth testing at this point just to be sure.
+=== Quick instructions for updating WeBWorK to the GitHub version ===
+* [[Upgrading_WeBWorK_with_Github]] more recent version of these notes for those already using github.
+*[[:Category:Release_Notes]]
-* Next we will create new versions of webwork and pg from the code base at github.com
-  git clone https://github.com/openwebwork/webwork2 webwork2_github
-  git clone https://github.com/openwebwork/pg pg_github
-* Particularly if you are using "sudo" you should check that the new webwork2_github and pg_github have  the same permissions and owners as the original webwork2_old and pg_old
-* The commands "chmod -R .....", "chown -R ", and "chgrp -R" will change the permissions, owners, and groups respectively on a directory, all of it's subdirectories and all of its files. Most often only the owner and group need to be changed.
-* Set permissions on subdirectories
-** We assume that your webserver is operating with user name www-data (other choices might be wwhttpd, _www etc.)
-** The webserver needs to own some of the subdirectories of webwork2
-   cd /opt/webwork/webwork2_github
-   chown -R www-data DATA logs tmp
-   chown -R www-data htdocs/tmp
-* Update mathjax
-  cd /opt/webwork/webwork2_github/htdocs
-  mv mathjax mathjax.old
-  git clone <nowiki>git://github.com/mathjax/MathJax.git mathjax</nowiki>
-* Notice that the last directory name has no capital letters unlike the command listed on the mathjax.org site.
-* See [http://docs.mathjax.org/en/latest/installation.html  mathjax installation documents] and [http://mathjax.org| MathJax] for more information.
-* If you are satisfied with new mathjax software you can get rid of the mathjax.old directory (which is probably empty anyway).
-  cd mathjax.old
-  rm -rf *  # insure that directory is empty
-  rm .*     # get rid of the .git files
-  cd ..     # go up one level
-  rmdir mathjax.old # remove the mathjax.old directory itself
-==== Configure WeBWorK ====
-* We set up the configuration files for the new code base. There are now three configuration files which replace global.conf:  site.conf, defaults.config, and localOverrides.conf.  The idea is that local configurations are set by modifying site.conf and localOverrides.conf while defaults.conf contains configurations that may be updated by new releases of WeBWorK but don't vary from one site installation to another.
-* The configuration lines in site.conf and localOverrides.conf all have analogs in global.conf so you should consult your old global.conf file for the information about your site needed to fill out lines in site.conf and localOverrides.conf.
-* If  site.conf and localOverrides.conf files already exist in your old installation you can copy them over from the old code base instead of creating new versions of the files as below.
-   cd /opt/webwork/webwork2_github/conf
-   cp site.conf.dist site.conf
-   cp localOverrides.conf.dist localOverrides.conf
-   cp webwork.apache2-config.dist webwork.apache2-config
-* Set up site.conf
-** This includes site information such as the database password.
-** The location of unix tools (the directory structure can change from on unix version to another). Locations of pdflatex and mysql may vary.
-** Time zone, mail server settings,
-* Set up localOverrides.conf
-** This provides overrides for defaults set in defaults.config.  No changes should be made directly in defaults.config.
-** Common overrides: Set the location of the OpenProblemLibrary (or NationalProblemLibrary).
-** Set the default theme; the default language; default display mode for equations; search paths for macro files, applets, etc.
-** Set defaults for the worth of problems, for showing equation editors (dragmath/mathview),
-** Set which editors are displayed to instructors.
-** Set date display formats
-** Set authentication methods
-** There is more documentation and suggestions in the comments with the localOverrides.conf.dist file
-* Set up database.conf.dist.  Because this configuration file is almost never customized for a local site we do not make a database.conf version.
-** You should remove or rename the database.conf file so that it is NOT referenced by webwork2
-** The presence of an old database.conf file is likely to cause database configuration errors. (See "what could possibly go wrong :-) " )
-  cd /opt/webwork/webwork2_github/conf
-  mv database.conf database.old  # move an existing database.conf out of the way
-* Set up webwork.apache2-config
-** This is seldom customized in basic webwork2 setups.
-** This contain apache setup stanzas for auxiliary applications interacting with webwork (e.g. moodle)
-* Update /opt/webwork/courses/modelCourse
-  cd /opt/webwork
-  mv courses/modelCourse modelCourse.old       # save current model courses
-  ln -s webwork2/courses.dist/modelCourse courses/modelCourse
-* This links courses/modelCourse to the latest distributed version of modelCourse. This means that new courses created from modelCourse will have new resources, such as those needed for the MathAchievements feature.
-==== Switch over to the new version of WeBWorK ====
-* Next we switch our links so that they point to the new code base.
-  cd /opt/webwork
-  rm webwork2
-  rm pg
-  ln -s webwork2_github webwork2
-  ln -s pg_github pg
-* Run check_modules.pl and update CPAN modules if needed.
-* Restart webserver.
-* Go to admin course, click on the "upgrade courses" tab and update the course databases.
-''' Enjoy'''
-* If something goes wrong and we need to back out to our previous version of WeBWorK simply change the links as described below and restart the apache server.
-  cd /opt/webwork
-  ln -s webwork2_old webwork2
-  ln -s pg_old pg
-==== What could possibly go wrong? ====
-* Everyone's environment is different, and everyone sometimes misses a step in the instructions so things might not always work the first time.
-* Don't panic!
-* On restarting the server you might get a (very long) error message saying something like:  "HTML::Scrubber not found after looking in ......".  This happens if a new CPAN module is used which is not immediately available on your system.  This can be installed with
-   sudo cpan HTML::Scrubber
-* If you have not updated for some time there might be several CPAN modules that need to be added.
-* Perhaps things seem to work at first but then fail when trying to enter a problem set with some information about "missing fields in table". This usually indicates that your course has an out-of-date database.  (This error will not happen with a freshly built course, only one that was built with a previous version of WW.)
-** Sign in to WeBWorK from the web and go to the admin page.  The url will be something like:
-  http://your.site.edu/webwork2/admin
-** Select the "upgrade courses" tab
-** Follow the instructions and upgrade the course that triggered the error (and any other courses that you expect to continue to use. You will be presented with a page where you can select which courses should be upgraded, followed by another page that informs you what database changes will be made, and then a page reporting the changes that have been made.
-* If the database error is not resolved
-** Check that the file database.conf has been moved out of the way (see above) so that the new database.conf.dist file is used for accessing the database.
-=== Quick instructions for using other branches of webwork ===
-You may want to use the current '''stable candidate release''' branch of WeBWorK instead of using the "master" branch.  You might want to do this because the upcoming release branch has a new feature that you want to use right away, or you might like to help out with the final testing of the new branch.  These instructions tell you how to
-download the new branch, how to switch to it, and how to easily revert back to the  original "master" branch if there are difficulties or when you are done testing.
-* These instructions tell you how to obtain recent branches of the webwork2 repository.  The analogous procedures on the pg directory will obtain the various branches of the pg repository.
-* To download the information about the branches of WeBWorK in addition to the master branch.
-  cd /opt/webwork/webwork2
-  git remote -v
-       origin	https://github.com/openwebwork/webwork2 (fetch)
-       origin	https://github.com/openwebwork/webwork2 (push)
-This is the default setup.  The reply to the remote command says that "origin" is connected to the standard repo at github.com.
-  git fetch origin
-  git branch -a
-    * master
-     remotes/origin/HEAD -> origin/master
-     remotes/origin/develop
-     remotes/origin/master
-     remotes/origin/release/2.7
-  git branch -t release/2.7 origin/release/2.7
-     Branch release/2.7 set up to track remote branch        release/2.7 from origin.
-  git branch
-     * master
-     release/2.7
-* This sequence of commands does the following
-** Obtain information about all of the branches at the "origin" repository.
-** List all of the branches available. The * indicates that we are currently using the "master" branch.
-** The "git branch -t..."  sets up a local branch which tracks (syncs with) the current release candidate (which is "release/2.7" in this case)
-** The final check "git branch"  shows that you now have access to two versions on the software, downloaded to your machine. The * indicates that you are currently using the master version.
-* Update pg (for some version changes it is necessary to update both pg and webwork2 but often they can be updated independently. The pg and webwork2 version numbers do not always match since pg is updated more frequently.)
-  cd /opt/webwork/pg
-  git remote -v
-       origin	https://github.com/openwebwork/pg (fetch)
-       origin	https://github.com/openwebwork/pg (push)
-  git fetch origin
-  git branch -a
-    * master
-     remotes/origin/HEAD -> origin/master
-     remotes/origin/develop
-     remotes/origin/master
-     remotes/origin/release/2.6
-  git branch -t release/2.6 origin/release/2.6
-    Branch release/2.6 set up to track remote branch        release/2.6 from origin.
-* Switch over the webwork2 release candidate release/2.7 and to pg version release/2.6
-   cd /opt/webwork/webwork2
-   git branch
-     * master
-     release/2.7
-   git checkout release/2.7
-   cd /opt/webwork/pg
-   git checkout release/2.6
-* Run /opt/webwork/webwork2/bin check_modules.pl to make sure that you have the required CPAN modules installed.
-* Now '''restart''' your apache server (the command for this might be  "sudo apachectl graceful")
-* Go to the webwork admin page   http://your.server.edu/webwork2/admin   and upgrade the relevant course databases.
-'''Notice:''' Configuration updates to webwork2 become relatively painless once you start using the new configuration files.
-* In most cases you will no longer have to update any configuration files.
-* Default configurations for new features will be automatically provided in the defaults.config.dist file.
-* Your local directory configuration structures remain unchanged in sites.conf as do your local overrides in localOverrides.conf.
-* Always customize configurations in default.config.dist by using localOverrides.conf.
-* You should seldom, if ever, modify default.config.dist. If you do, you become responsible for managing and merging changes to that file.
-It is also easy to back out to a previous release.
-* To switch back
-   git branch
-     master
-     * release/2.7
-   git checkout master
-and '''restart''' your apache server.
-==== What could possibly go wrong ====
-* You get what look like database errors of some kind -- missing fields in tables, etc. when looking at a course.
-** Most likely you didn't upgrade the course databases from the web using the WeBWorK admin page
-* You get a long message about "not finding HTML::Scrubber" looking in ..... various directories
-** The message looks scary but simply indicates that some required CPAN module has not been installed on your site.  Perhaps you forgot to run check_modules.pl or perhaps the maintainers neglected to include a required module in the new version of check_modules.pl. (If this is the case please report the bug.) They are easily installed using the cpan command or by importing them from your distributions packages.
-=== Quick instructions for updating one of your branches ===
-* To update one of the standard webwork branches
-  cd /opt/webwork/webwork2
-  git branch
-     * master
-     release/2.7
-  git pull
-This updates the current branch "master" to agree with any changes that have been made on the openwebwork repo. If you wish to update the release/2.7 which is tracking release/2.7 on the openwebwork repo then follow the same procedure but first switch to the release/2.7 branch using the command
-   git checkout release/2.7
-* Those wishing to update from other sources than github.com/openwebwork should read the WeBWorK developer instructions for using the advanced features of git.
 [[Github Overview]]
-== Download WeBWorK via svn to an svn repository==
-* Quick-instructions. Type the following in the directory where you wish to have the repository. For example:
-          <nowiki> cd webwork
-          svn checkout https://github.com/openwebwork/webwork2/trunk webwork2
-          svn checkout https://github.com/openwebwork/pg/trunk pg
-          svn checkout https://github.com/openwebwork/webwork-open-problem-library/trunk   webwork-open-problem-library
-          </nowiki>
-  will produce the directories webwork2 and pg inside the directory webwork containing all the files from
-  the master versions of webwork2 and pg at the github.com/openwebwork repository respectively.
-* For more details see the documentation by the github folks: https://github.com/blog/966-improved-subversion-client-support
 == References for GitHub and Git ==
@@ Line 247: / Line 31: @@
 * Version Control by Example by Eric Sink which is available at http://www.ericsink.com/vcbe/
 * http://nvie.com/posts/a-successful-git-branching-model/ a potential workflow model for WeBWorK development -- we're still working on refining a workflow
-* see also [[Git]] for more references
+* see also [[Github Overview]] for more references
 [[Category:Version_Control]]
 [[Category:Installation]]
-[[Category:SVN]]
 [[Category:Github]]