Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Make sure you have git setup and have a github account and have your name and email properly set as git global variables on your workstation.
  2. Fork the central Sakai repository to your own github account
    1. We will use the following references
      1. local = local git clone on your workstation, this where everyone typically does their work
      2. origin = this is your local fork of the sakai project on github, you clone this repo on your local workstation
      3. upstream = this is main sakai project github project everyone forks this project into their github account
  3. Clone your fork onto your computer
  4. Sync sakai master with your local forks master to receive updates
    1. Never work on your local master, generally this branch should always be the same as what is in sakai's master and if you make commits here this complicates things.
    2. Sync sakai master with your forks master

      master>

      git

      remote

      add

      upstream

      https://github.com/sakaiproject/sakai
      (you

      will

      do

      this

      only

      once)

      master>

      git

      pull

      upstream

      master
      (you

      will

      update

      your

      local

      fork

      frequently)

      master>

      git

      push

      origin

      master
      (after

      you

      update

      your

      local

      fork

      don't

      forget

      to

      push

      to

      your

      github

      fork) 

       

  5. Use your own copy of git to make your changes and test, etc. You can commit and push as to your own repo as much as you like.
    1. Make sure you always work on a local branch, We recommend using the name of the JIRA as the branch name.
      master> git checkout -b SAK-12345
      SAK-12345>
      (make your changes then commit them, if you make multiple commits its best to squash them into one logical commit)
      SAK-12345> git push origin SAK-12345
      (this creates a new branch called SAK-12345 in your fork on github that contains everything in your local branch SAK-12345, notice they have the same name this is important)

       

  6. When you are ready to "commit to trunk" create a pull request from your repo against the sakai master branch in the sakaiproject repository.
    1. If the changes are code you would have committed to the old SVN trunk (i.e. just normal development) - merge your own pull request in to Sakai's master branch.
    2. If the changes you are making are worthy of further review or touching an area of Sakai that you do not generally work in - have someone else review and merge your pull request.
    3. If after review changes need to be made all you need to do is make the changes and commit in the SAME branch you issued the pull request (PR) from and then push those changes to your fork and it will automatically update the PR that was made to sakai's master.

...

Typical git workflow would go like this (assuming everything is setup as explained above):

  • goto go to master and get the most recent updates
  • create a new feature branch to work in (remember never work in master)
  • switch to the feature branch if needed
  • work on your local feature, creating as many commits as needed
  • once you are happy with your changes and believe it is ready for inclusion in sakai's project (upstream) squash your commits into 1 commit
  • push your changes to origin in a branch typically with the same name
  • next issue a pull request (PR) from your feature branch in origin to upstream master
  • if review is needed this is the time for others to review your changes
    • if further changes are required you switch to your local branch make the changes and commit and then push them to the same branch in origin that the PR was issued from and PR will be updated automatically.
    • repeat this step until changes are satisfactory
  • if review is complete then the PR is merged
  • optional branch can be deleted in origin when PR is merged

...