Contributing. A Git Tutorial.

Mon, Dec 19, 2022

Back when I was just a wee tyke me mummy used to bake these tasty little gits every year for my birthday.

Haha. Oh those are fun stories aren't they?

Jk. They're not. Usually anyways.

Let's get more serious. I have wanted, for like eons, to begin contributing to an open source project. It's been a goal, or dream, of mine ever since I first got online and started learning about what open source software was. As soon as I'd heard of it, I began to try and use open source software whenever I could. The more and more I used open source programs, the more I felt I wanted to give back. To help. I like to try and be a helpful person. Hence, trying to write some tutorials.

But as close as I've come to making that first contribution over the years, it had never happened. Until now, just a few days ago.

I've recently been working through getting my personal Calkey instance up and running. And so far, it's been a great learning experience for me. I've learned a lot more than I previously knew about Docker, SMTP Email Services, and git. And this has also led me to making my first contribution to an open source project. It may be an incredibly, absolutely tiny, micro contribution. But getting to understand the git work flow a lot better and submitting my first ever PR to a project feels really cool. So I'm considering this as the first of my contributions to the open source community.

What I wanted to do here is, kind of walk through a bit of what I feel I learned, in very plain beginners English. Somewhat for you, but mostly just for me. So I can take a glance back at later. When I inevitably don't do this very thing for a much longer than expected period of time after which I've forgotten a bunch of stuff and wish I had maybe jotted some notes down for myself before I again scour the internet for places where someone else maybe wrote up something similar to what I'm doing here. /ramlbe

The how do I contribute workflow...

Consider Yourself Notified: I really don't know what I'm talking about with a lot this stuff, so tread cautiously in utilizing anything I've written here for yourself. My experience is as a hobbyist programmer just playing around for funsies in his spare time. I read things. They get jumbled up. I may not always use the right or most current terminology. I have ZER0 professional experience with a most of these things. So please do feel free to give me any comments below if you think I have something way wrong. I'll gladly make corrections.

So a long long time ago before git was discovered, all open source software was kept collectively in a single big notepad.exe text file that everyone passed around on floppy disk. But now, since git was found, and it was the first and is the only software versioning system to have ever existed, git is how every single open source software program is maintained and collaborated on.

Just kidding. Absolutely none of that is true. I really don't know much about the history of how open source programs were worked on in the past, but today, it sure does feel like git is the only way it's done. I do know there are other version control systems out there, uhm... subversion(?) I think is one. I don't know why git has become so popular and wide spread, but it has. It's just the way it is. So we all now just have to deal with that. I've heard that some people are a bit critical of git and it's popularity, but I don't know much about that either. I just wanna do shit. And not just worry about what's shit or what's not shit. Because everything is going to be a little shit in one way or another. So let's not worry about that shit.

Gits not hard. Gits not easy. On one hand, if you're at all comfortable in the command line, executing git commands is pretty easy. I mean yeah. It's pretty darn easy to just type things into a little box, press enter, and watch stuff happen. The hard part is knowing when and which commands you need to run and why. It's getting your head wrapped around this workflow. Things, at least for me, can get feeling really complicated and confusing very quickly. Even though I've now gone through this process and certainly feel a bit more familiar with git - or the workflow - now, it can still get back into the complicated and confusing arena fast.

If you are talented enough, I suppose, you may be provided the ability to contribute to an open source projects git repository directly. I, am not yet that talented. So this walk-through of workflow is going to focus on creating your own fork of a project, so that you can submit a PR to the project, so they may merge your modifications into the main projects repository.

Ok, so go create your fork. Are you done? Great job!

No, but seriously, I'm not going to be getting too deep and detailed on how to execute each and every step here. We're keeping this kind of high level flow charty, but more words and less shapes and lines.

Creating a fork is pretty much the same on I think most of the git hosting sites (e.g. Github, Gitlab, Codeberg, wherever). You create your account, go to the projects main repository, and then click the fork project or whatever button somewhere on the page. Than you'll have your own complete copy of the project that you can do whatever you like with. Break it. Break it good.

Now I don't know if this really matters or not, but when I forked the Calkey repo on Codeberg there was a checkbox to make my forked repo private. I was trying to check it, but it wasn't working for some reason. I kind of feel like if you're not intending to modify for re-distribution, you should probably make your forks private. Maybe? I don't really know if that's right or not, or if anyone really cares. I was just thinking why would we want a lot of public forks just cluttering things up if you're just using it for personal development and to feed back to the main project.

Once you have your project forked, you're all set to start working. This forked repo is where you will make your modifications, or patches, and then request to have those changes pulled upstream into the main project repo.

Once you've cloned your newly forked repo down to your machine. You can begin The Work ® © ™. Yeah. Right after cloning is where I start to get sorta confused.

Most of the time, you're gonna be sitting there just chilling on main [~branch~] , keeping things synced up with the main project repo. Until you get hit with some inspiration and you're all like "Yah! I'm gonna implement this cool new feature!". Or you run into a bug and you're all like "Ah poops! I need to fix this!".

So now that you've found some bug inspiration, you've got some work to do. Always starting from the main (updated) branch, you create a new branch. A branch to track all of the changes you're going to begin to make. When you're happy with the work you've done, and you've given it a good razzle dazzle of a testing, you can go ahead and add > commit (with comment) > push all of those changes to your forked repo.

At this point, you will now have your new branch showing up on your CodeGitGitHubLaberg page. It is now that you can select your branch and click the PullRequest button, wherever it is on the page, to ask the main projects administrators or whatever they're called, if they would kindly merge your modifications into the main project.

And that's it. You did it! You submitted a modification to to an open source project. If your modification gets merged, you have successfully made a contribution to an open source project. You helped. Kudos and cheers.

So, there is probably something else I have to figure out here and add. I'm guessing that I would next merge my branch into my forked main repo at this point. But yeah, I think for me at this point I would merge my new branch I PR'd into my forked repo main branch. But then I could not (but why would I want to?) update from the upstream repo until my modifications were merged into the main repo. But then if the main gets an update that I want to pull, but they didn't merge my branch yet (or at all) and I want to keep that as well... and I'm lost and done for now. Need to read and practice a bit more and sort this out. /ConfusedRambling

Figures. In looking something up just now to refresh my memory I found the giteveryday page on the git site. I would probably recommend, if you've made it this far into this steaming pile of hot sticky rice, that you go check this page out for a far more correct and detailed write-up that also probably has much better grammar too. And never come back here again.

Also, Atlassian has a great tutorial on this exact topic. It's he one I learned a lot from to regurgitate into this pile of manure right here.

Go forth and contribute my minions! And by minions I mean all 1.75 of you that will read this.

Clone
Copy the repo from your git hosting site of choice to your local machine. git clone [http or ssh address of repo].
Remote
Use with -v to show the remote repos your clone is connected with, git remote -v.
Use with add upstream to add the main project repo so you can keep your project sycnhed, git remote add upstream httpOfMainProject.
Status
Get the status of your working branch. git status will show you what files have been modified and not committed.
Add
Add modified files you are ready to commit. git add . will add all modified and uncommitted files. You can also add individual files by file name.
Commit
Prepare your added files to be pushed by adding a comment. git commit -m "Comment wuz here".
If you omit the the -m option, your default cli text editor will open and you can write fancier and lengthier comments for your commit if you'd like.
Push
To uh, push your changes to your repo. Clever naming there eh? Your freshly modified, added, commited, files, can now be sent off across the internet super highway, to be published in your repo with git push origin [BranchName]. Omit BranchName to send all commits to your online repo or include the BranchName to only send the commits from that branch.
Fetch
To update your cloned repo with the latest branches and tags from your remote repo. If you include upstream, it will also get the updates from the main project repo, git fetch upstream.
Checkout
For switching to your different branches, git checkout [SomeBranchName].
Merge
For merging things into other things. Duh. If you're working in your repos Main branch, and want to update it with upstream projects Main branch to make sure your forked repo is up to date, you'd do git merge upstream/main.

There might be some more I should probably add, maybe I will later. Good luck! Have fun!

  1. Previous Post
    Need SMTP? A Tutorial.
    Wed, Dec 14, 2022
    Tutorials Calckey SMTP
    Setting up SMTP to use with Calckey so you can send administrative emails.
  2. Next Post
    From Apache to Nginx
    Mon, Dec 26, 2022
    Tutorials Apache Nginx
    A basic tutorial to migrate from Apache webserver to Nginx webserver.