GITHUB and proper procedures

Intro

GITHUB is a wonderful collaboration tool for developers. We at PCGen are migrating from the SVN repository we host of SF to the free hosting at GITHUB. Most people should be familiar with GIT and GITHUB, but we'll go over what our procedures are:

Contributor Setup

If you plan on being a developer and contributing follow these steps:

• 1) Sign in to github with your account. (You should have a SSH key)
• 2) Navigate to the pcgen project you wish to contribute too and click the FORK button. (See below for link)
• 3) Navigate to your FORK of the pcgen project and use the SHH link for cloning a local copy
• 4) Choose a local folder to house your local copy and clone the copy there.
• 5) Add a remote repository and link it to the main pcgen project (or upstream) -- OPTIONAL STEP: This allows fast update to your local copy from the main project, see https://help.github.com/articles/syncing-a-fork/.
• 6) Once your local copy is downloaded, do a git checkout and name your branch* (See Branch Naming practices below)
• 7) Once you have finished working on your feature/bug branch, do the git equivalent of 'add', 'commit', and then 'push' those changes to your remote repository. (See GIT Commit Summary Practices)
• 8) Do a PR (Pull Request) from your repository to the main pcgen repository, using the branch you pushed in - make an explanation summary or JIRA ID

Just want a Copy of a project

If you want to maintain an up-to-date copy of the pcgen project repository, but do not have plans to contribute in the near future, you may easily do the following:

• 1) Navigate to the pcgen project repository (See below for link)
• 2) Click the "Link" of your choice for cloning a local copy - SSH is superior, but you may opt for https.
• 3) Choose a local folder to house your local copy and clone the copy there.
• NOTE: This will allow you to grab updates from the project, but not push any changes.

Of course, you are always able to use the download, to get a snapshot of the project. This is the least recommended method of having access to the project.

Feature/Bug Branch Naming Practices:

• All Features or Bugs should have a corresponding JIRA ID, example: CODE-1234, or DATA-4321. Your Branch should be JIRA-ID_Title, example: DATA-1234_Fix_Bard_Skills

SSH Keys are useful and should be used whenever possible. For Windows, PuttyGen will allow you to create your own SSH Key.

Git Commit Summary Practices

• Each Commit you make should include the JIRA-ID for point of reference and JIRA integration tracking
• Each Commit you make should include enough detail to understand what you were working on

• Before PUSHING, you may do any number of things to clean up before you PUSH to the remote. Please review the options from reputable GIT information sites for proper usage.
• Ideally, you should squash your commits into one commit before pushing into your remote.

There is a useful aide-memoire on GitHub, https://github.com/PCGen/pcgen-newsources/wiki/Contributing-to-NewSources.

PCGen Projects

All Active PCGen Repositories are held under the Username "PCGen" which is our organization on github.com. You can find the repositories we host here: https://github.com/PCGen

• Our Main Development Program is "PCGen" - git@github.com:PCGen/pcgen.git
• Our New Source Development is NewSources (Active Now) - git@github.com:PCGen/pcgen-newsources.git

GIT TOOLS

• Command line for GIT is by far the superior method. However, we have found tools that our developers like to use and recommend them as easier alternatives to the command line if you choose to do so.

Windows

• Atlassian's free SourceTree GUI program (SourceTree Helpful Tips)
• TortoiseGIT (Shell integration)

Mac

• ...Pending...

Linux

• RabbitVCS (Gnome only, integrates with Nautilus)

Branches and keeping in sync tips:

• In GITHUB you can do this by:
• git checkout master
• git fetch –f upstream
• git rebase –f upstream/master
• git push –f origin

That will make your master branch a mirror of the upstream master branch. Then if you kept your working branch and expect to continue work in that branch rather than creating a new branch, you would:

• git checkout mybranch
• git rebase –f master
• git push –f origin