Difference between revisions of "Github"

From WeBWorK_wiki
Jump to navigation Jump to search
 
(121 intermediate revisions by 8 users not shown)
Line 1: Line 1:
  +
===Installation Manuals===
   
−
{{warning |This page is still under construction use with caution}}
  
  +
see [[:Category:Installation Manuals| Current Installation Manuals]]
   
  +
=== WeBWorK software download ===
  +
WeBWorK online homework software is located at http://github.com/openwebwork.
  +
webwork2 -- the instructor and user interface
  +
pg -- the macros for rendering questions
  +
webwork-open-problem-library -- library of 35K+ homework questions
   
−
== GitHub ==
 +
=== Github Overview ===
  +
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.
   
  +
=== 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]]
   
−
===Overview===
 +
[[Github Overview]]
−
Git is the name of a distributed version control system. It plays the role of the CVS or SVN control systems that WeBWorK has used in the past
  
−
but the details of how it works are somewhat different. For obtaining up-to-date copies of software there is not much difference between git
 
−
and previous VCS. Developers however should read closely since git has a different conceptualization of how version control should be handled.
  
−
The difference allows considerably more flexibility for collaborative development. Consolidation no longer depends on a single site or single
  
−
administrator. Updates are also more modular and therefore easier to check and repair or remove if they cause trouble.
  
−  
−  
−
Git has many capabilities and can be used in many different ways. This page outlines a subset of git commands and workflows that seems to work
  
−
well for WeBWorK.
  
−  
−  
−
'''Github.com''' is a site which facilitates the collaborative development of open source projects. These sites are open (read-only) to the world.
 
−
WeBWorK has a master site at https://www.github.com/openwebwork where accepted modifications are being consolidated. The following repositories are
 
−
available at that site.
  
−
* webwork2 -- the course management face of WeBWorK
  
−
* pg -- the macros that help render the PG questions
 
−
* webwork2-dev -- development version for the latest features -- still stable -- it will run but there may be some surprises.
  
−
* pg-dev -- development version for the latest features -- still stable -- it will run but there may be some surprises.
  
−
* WeBWorKOpenProblemLibrary -- WOPL -- (formerly NationalProblemLibrary) -- a collection of questions
 
−
* wwmoodle -- plugins that connect moodle and webwork
  
−
* ww_question_server -- another plugin project connecting moodle question types to the WeBWorK webservice
  
−
* admintools -- a collection of command line scripts used by larger sites serving WeBWorK
  
−  
−
=== Following WeBWorK Development ===
  
−
You can get a view of development using git by clicking on the "Network" button on a github site.
 
−
For example at https://github.com/mgage/webwork2 click on the "Network" button to see a graph of changes incorporated into Mike Gage's (bleeding edge) version
  
−
of WeBWorK. Clicking on the commit dots along the lines will show the commit comments describing what was done with this commit. With git you concentrate on the "dots" the individual commits, more than the branch lines. You can often grab individual commits and apply them to your own branch; cherry picking some features for your branch while leaving other features behind. Your branch and the branch you are borrowing from must have a shared history somewhere in the past. Having a fairly recent shared history minimizes the chances that there will be conflicts when you try to apply the commit or "patch".
  
−  
−  
−
You can scroll the network graph to explore the past history of WeBWorK and when (and to some extent by who) each feature was added. Please follow or improve on the style of the later commit comments. Earlier commits represent a learning phase. :-)
  
−  
−
[[File:github_project_network_graph.png]]
  
−  
−  
−
The top lines indicate worked done by Mike Gage locally on his laptop and eventually merged into his master branch and uploaded to the github repository. The other lines indicate work uploaded by other developers to their sites and where their development repos stand compared to Gage's.
  
−  
−
=== Contributing to WeBWorK ===
  
−  
−
=== Workflow ===
  
−
On your local git repository the following workflow seems to minimize clashes with work being done elsewhere.
  
−
Commit early and often to your local branch.
 
−  
−  
−
clone the remote repo
 
−
git checkout -b my_new_feature (start a new branch to work on a single feature)
  
−
..work and commit some stuff
  
−
git pull origin master (pull changes from the upstream github repository into your master copy)
  
−
git rebase master (apply updates to your my_new_feature branch so that it looks like it branched from the updated master copy)
  
−
..work and commit some stuff
  
−
git pull origin master
 
−
git rebase master
  
−
..finish the feature
  
−
git checkout master
  
−
git merge my_new_feature (merge your changes back into your local master copy)
  
−
git push origin master (publish the changes in your master copy to your github account)
  
−
git branch -d my_new_feature (delete this branch. Since you don't want to use it with rebase after you have submitted to the github repository? )
  
−
 
−
Issue pull request to openwebwork
  
−  
−  
−
The use of "rebase" means that your chain of commits will all appear together, one after another, without any intervening commits from other developers which makes it easier to understand the flow of development. In general, even without rebase issues, it is better to delete your feature branch once you have merged it with your master branch and tested it in order to avoid clutter. git will not allow you to delete a branch (easily) if it has not been merged with the master branch.
  
−  
−  
−
Individual developers for webwork also have their own sites (analogous to the branches in SVN, but more easily accessible)
  
−
* Michael Gage: https://www.github.com/mgage
  
−
* Jason Aubrey: https://www.github.com/aubreyja
  
−
* David Gage: https://github.com/whytheplatypus
  
−
* Arnie Pizer: https://www.github.com/apizer
  
−  
−
=== Writing a good commit line ===
  
−  
−
Writing good commit lines is important. Imagine that you will be reading a series of commits in order to understand how the software
 
−
development is progressing. Write accordingly.
  
−  
−
When making commits I found this advice to be useful.
  
−
*'''Write a good first line''' that describes the feature you are committing . (It's like the subject line of an email but more important) This is the line that summarizes the commit so that when searching the commit tree one can find where a feature was added.
 
−
* Good style: Start with a verb in the present tense. These read well in the commit tree. For example:
 
−  
−
Add slider bar to library browser.
  
−
or
  
−
Fix bug in level_curve_checker subroutine
  
−
* '''Follow the subject line with a blank line.'''
 
−
* Then add as much as you want to explain what changes were made and any other information you want preserved. (A diff of the changed files is preserved automatically.)
  
−  
−
* You can use git log to see how previous commits were worded. (Don't copy any of my first examples, but the later ones are getting better.)
  
−  
−  
−
*when possible make each commit an atomic unit. One step in the development process
  
−  
−
== 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:
  
−
cd webwork
  
−
svn checkout https://github.com/openwebwork/webwork2/trunk webwork2
  
−
svn checkout https://github.com/openwebwork/pg/trunk pg
  
−
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 ==
  
== 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/
  
* Pro Git book http://progit.org/
Line 15: Line 25:
 
(unreviewed at the moment -- YMVV)
  
(unreviewed at the moment -- YMVV)
 
*http://gitref.org/ quick reference
  
*http://gitref.org/ quick reference
−
* http://help.github.com/send-pull-requests/
 +
* https://help.github.com/articles/using-pull-requests
 
* https://github.com/blog/966-improved-subversion-client-support
  
* https://github.com/blog/966-improved-subversion-client-support
 
* git cheat sheet: http://byte.kde.org/~zrusin/git/git-cheat-sheet-medium.png
  
* 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/
 
* Version Control by Example by Eric Sink which is available at http://www.ericsink.com/vcbe/
−
* see also [[Git]] for more references
  
  +
* 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
   
−
[[Version_Control]]
 +
[[Category:Version_Control]]
  +
[[Category:Installation]]
  +
[[Category:Github]]

Latest revision as of 12:54, 7 October 2021

Installation Manuals

see Current Installation Manuals

WeBWorK software download

WeBWorK online homework software is located at http://github.com/openwebwork. 

webwork2 -- the instructor and user interface
pg       -- the macros for rendering questions
webwork-open-problem-library  -- library of 35K+ homework questions

Github Overview

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.

Quick instructions for updating WeBWorK to the GitHub version

Github Overview

References for GitHub and Git

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

(unreviewed at the moment -- YMVV)

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=Github&oldid=22483"