Basic Git Flow For Making Open Source Contributions on GitHub
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!)
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.
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.
- Open Command Prompt, Powershell or a Git Bash terminal window and change to the directory in which the GitHub repo has been cloned.
git status to see if I am current on my
- If not already on
git checkout master to switch to my local Git repo's
git branch to list all branches currently on my local Git repo
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)
git pull upstream master to make sure my local
master branch is in sync with the upstream
git push origin master to make sure my forked (origin) GitHub
master branch is in sync with my local and upstream
git checkout -b issue-177 to copy my local
master branch into a new branch named
- Make changes to the code and test locally
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)
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.)
git push origin issue-177 to push my local repo branch to my forked (origin) GitHub repo
- 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.
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!
blog comments powered by