If you've paid attention this entire time, there were 3 previous posts:
This post will close the final loop related to source control, as I've covered most things you can do. As I have previously mentioned, source control is vast and despite these posts getting you more comfortable and maybe even technically savvy with source control, there are still expert or advanced levels I will not cover. My goal is to take the traditional system engineer or administrator and bring them up to "ninja" level with their colleagues. Note, this is more like a perpetual green belt to developers, who have been dealing with source control their entire careers. ;)
So forking, aye? In the world of development, forking a project traditionally meant someone took the current code base and used it as a basis for a separate or alternative project. With git, a fork of a repository is a copy of that original repository, with all its code, branches, and history. The fork also knows from which repository it has been forked. A fork can be thought of as another clone of a repository. All major distributed source control systems have this core functionality built in.
The biggest component is if you fork an original repository into your own environment, you can contribute back to the original project. Ruby on Rails is a good example and is referenced often in explaining the process of forking to everyone. The project currently has over 20,000 forks on GitHub. Now, that doesn't mean there are over 20,000 competing versions of the source control out in the wild, so to speak. That means over 20,000 people are actively contributing to the source code. Pretty nifty, aye?
Microsoft open sourced all documentation a number of years back to correct spelling errors, technical errors, and to correct outdated technical information. The fact that anyone can contribute is saying something to the future of making Microsoft's documentation the best it can possibly be!
In order to contribute to the documentation, the concept of forking needs to be demystified a bit for folks newer to the notion of source control in general (what I presume my audience to be). Each major area of Microsoft's documentation has a contributing markdown file, so if you're really going to contribute, make sure you read through each of these documents after you fork and before you create a pull request (PR). All Microsoft documentation lives here: click me. If you're curious as to what a contributing file looks like, click through the following two repos for more information (they're the repos I'm most familiar with):
1) Microsoft Azure Docs - Contributing File
2) Microsoft 365 Docs - Contributing File
As you can tell, Microsoft documentation is vast. At the time of this writing, there are 5,800 repositories. Gah...that's a lot! So forking can help you help Microsoft out with fixing any errors that may show up within Microsoft's documentation.
So how do you fork and contribute? This is where it gets interesting (at least in my mind). Let's cover the steps here and you can test everything out at your convenience. Note, I've already forked a number of Microsoft repos over into my GitHub account and I don't have anything to submit a PR for, so what I will do is fork a repo to my GitHub organization I built out when I was familiarizing myself with GitHub's offerings a few years ago.
Let's take my example repo and work from there. At the top of every GitHub repo, you should see a "Fork" option. Click on that "Fork" button at the top of the repo you're going to use:
Select the organization or profile you're going to fork to (so even though I'm not doing it this way, select your personal GitHub account if you're forking any of the Microsoft Docs repos for various products) and click on "Create fork":
When the task completes, you will be taken to your GitHub profile and you will see the following information at the top:
1) The repo will keep the same name, however it will be listed with your account first (versus what shows up in the public repo).
2) The forked copy will say "forked from..." and then list the actual account and repository the fork came from. Take a look at my example:
Next, let's switch to the cli for git commands!
Navigate to the repository you want to clone this forked repository to. Once there, create a directory and navigate into that directory from the command line:
Grab the HTTPS link at the top of your forked repository, as we've discussed in my previous post:
Switch back to your shell prompt and issue out the following command shown in the screen shot below. Git will clone the repository to your local machine. From the same directory, run ls and see the output + structure:
The git commands you typed will create a folder structure and if you browse into the folder structure, you will see the original files from my sample repo.
Super cool. Ok let's edit the files like we did in my previous post. The harry.txt file will have "The boy who lived.", the dumbledore.txt file will have "Dumbledore died.", and the snape.txt file will have "Snape's not a bad guy."
After you've made these changes, switch back to your shell prompt once more. Type in git status to see what's been affected with your local changes.
After examining the output from git status, you should see the right files have been changed and we're ready to start committing the files to your fork on GitHub. These commands will feel familiar to you (remember my previous post?):
At this point, you will have added the changed files to the local commit, committed those files locally, and then pushed the files to the fork. Let's check out the fork:
The files we edited locally are now committed and pushed to the fork that exists in my organization on GitHub (the 3 files edited 2 minutes ago, per my screen shot0. You might also see that GitHub tells me this branch (or fork) is 1 commit ahead of sbkuehn:master (where the actual main repository lives). Let's create a PR to master/main (note, newer repositories will be main, so know this is an older repository before the change was made).
First click on "Contribute" and then click on "Open pull request":
On the "Open a pull request" page, for this simple tutorial, you will want to make sure the base repository is the original repository you want to contribute to. The head repository is your fork. The different branches in this example use "master", but it could be a separate branch in either scenario. I always recommend putting something in the written section of the PR, as you never know all the requirements you need to meet when contributing to existing projects (this is why examining the README is so crucial). After you've filled everything in to the best of your abilities and made sure the PR follows specific guidelines for the maintainers of each repo, click on "Create pull request." In this example, take a look at what I've configured:
You will then see a screen that looks like my next screen shot. Note, if you're contributing to any Microsoft repository, you will not be able to merge the pull request (someone needs to review the material you submitted via the PR):
The maintainers of the repository will receive an email about this PR you want to submit and they will see an open pull request in their detailed view of the repository they maintain:
After clicking on the PR, the maintainers of the repo will see a similar screen as shown above where they can select "Merge pull request."
And that's it! I went through a basic forking example and mileage will definitely vary. The biggest thing to stress is read through the entire README file so you know what the maintainers of the repo are looking for. This helps them merge your pull requests faster and then you can contribute to open sourced projects like a functional IT practitioner!
With that, we've reached the end of this series. Remember, you should now be a ninja if you're an IT Pro and you'll be a green belt if you're talking to devs. :) Happy coding and happy source control to you!