The Confusion

What the heck is Git and GitHub and how do I use them?  There are so many open-source projects out there that I'd love to get involved in, but I don't have a clue how to Git what I need!  Can you help?!?!?  I have tried, but I have done nothing but embarrass myself and mess things up for others.

Is this you or does it represent your fears?  Well, don't worry!  I and many others have been there and have done that too! (I'm even thinking about getting the t-shirt that says so!  Do you have one of those designed yet Will Strohl?  LOL!)

The Backstory

I have been asked the above so many times and it is finally time I publish this blog about the subject.  In doing so, I hope this serves as a nice starter reference for those in our community that would love to get more involved with DNN Platform or other community open source projects.

There are many ways people go about using Git and interacting with GitHub.  Some prefer a combination of the browser and desktop applications such as SourceTree or GitKraken.  I personally prefer the Command Line Interface (CLI).  Using the CLI takes time to learn commands and such, but it also really helps solidify your understanding of Git and ultimately helps you to be faster and more efficient in your workflow.  While the following is somewhat subjective, I find it is a really good general workflow for making open source contributions.  Each time I want to work on an Issue logged in a GitHub repo, I follow the below steps. 

The git-flow

For the purpose of this example, we will be referencing Issue #177 on the nvQuickTheme GitHub repo.  At the time of the writing of this blog, this issue is in an Open status.

1. Open Command Prompt, Powershell or a Git Bash terminal window and change to the directory in which the GitHub repo has been cloned.
    
2. git status to see if I am current on my master branch
    
3. If not already on master branch, git checkout master to switch to my local Git repo's master branch
    
4. git branch to list all branches currently on my local Git repo
    
5. git branch -D <branch-name> for any branches I need to delete (it is ideal to keep your local repo as clean and uncluttered as possible)
    
6. git pull upstream master to make sure my local master branch is in sync with the upstream master branch
    
7. git push origin master to make sure my forked (origin) GitHub master branch is in sync with my local and upstream master branches
    
8. git checkout -b issue-177 to copy my local master branch into a new branch named issue-177
    
9. Make changes to the code and test locally
    
10. git add . to stage all changes for local commit (by the way, a . should not be used if you only want to stage a subset of files that were changed - for that you can use git add <file-name> for each file you want to stage)
     
11. git commit -m "Add optional 'hidden' LOGIN theme object" to commit changes to my local repo (For the message, I typically use the title of the GitHub issue I am working on, as this really helps keep things nice and organized for repo owners/maintainers and makes it obvious what was done for the commit. For more complex issues, requiring multiple commits prior to submitting a pull request, I use more meaning messages related to each commit.)
     
12. git push origin issue-177 to push my local repo branch to my forked (origin) GitHub repo
     
13. Visit forked (origin) GitHub repo or main (upstream) GitHub repo in my browser to create the pull request (PR). In the PR description, I would use the special GitHub keywords mentioned HERE to reference the issue for which this PR relates (in this case Resolves #issue-177). This is important for repo owners/maintainers because it allows the referenced issue to be auto-closed upon merge of the pull request.

The Wrap-Up

There are certainly more complex scenarios that come up from time to time, but the above is a good general git-flow for most scenarios. I really hope this helps!
 

This blog has been cross-posted from www.davidpoindexter.com