Version Control Basics

Software to download and install:

Windows:

Git Bash: https://gitforwindows.org/

macOS:

Homebrew: https://brew.sh/

Check if git is already installed using git –version in a terminal window. If it’s not already installed, install it with homebrew:

brew install git

Linux:

sudo apt-get install git

Open source contribution is the fulcrum of online developer communities. GitHub is at the forefront, though it is by no means your only option. Any modern developer worth their salt can’t afford to ignore version control systems like git and the communities that are based around them. English being the lingua franca for many countries has some perks for software developers. Programming language syntax and technical documentation tend to be in English, which means it shouldn’t be that hard to learn online or contribute to open source projects, even if the contributors are all across the globe.

Version control system – a version control system lets you keep track of changes made to code. Let’s face it – programming is complicated. And if you introduce a new change to your code, you can potentially break everything. Then you might forget which particular lines you changed, and it can be hard to go back to an older version. Prior to implementing a version control system, your coding habits might be more circumspect out of fear of breaking something that you can’t fix.

Before I started using a version control system, I would make a copy of my project folder and rename it to project_name_BACKUP_PRE_FEATURE_X, where X is whatever feature I was working on at the time. I realized the need for keeping track of different versions, and I had vaguely heard of git, but I never really used it because it seemed complicated and daunting. But you know what else is daunting? Dealing with manual backups.

  1. There are multiple version control systems, such as git, mercurial, and subversion, a.k.a svn. I only use git, because that’s the most popular one at the moment.
  2. Simply put, git allows you to keep track of changes, make new changes, revert to old versions if necessary, and also lets multiple people collaborate on the same software project, even if they’re in different areas.
  1. Before I learned git, I attended a couple of workshops about the subject, but they made it seem more recondite than it actually is. Inadequate explanations can be counterproductive.
    1. GitHub – GitHub is a popular site for hosting git repositories. You don’t have to use GitHub with git, but many people do for many reasons. For one, there is a vast developer community centered around GitHub (and sometimes Twitter). If you’re an aspiring developer, you’ll need to make some personal projects, such as websites and apps, and you should put them on GitHub so people can see them. Not everything is suitable for public viewing though. For example, in computer science classes, a professor might ask the class not to upload assignments to GitHub so that nobody can copy and paste someone else’s answers. Or you might have some unfinished or sloppy code that you don’t want other people to see. But overall, GitHub is vital, and you will need to use it at some point or another, so you might as well learn it soon.
  1. Proprietary software – when you don’t let people see your source code, your code is considered to be proprietary (if you let people download compiled versions of it that they can’t see the inner-workings of). When you don’t share your source code, you can get away with abysmal design choices because no one will be critical of them. When something is open source, people can see your code – and assess how good or bad it is. Never letting people see your source code can mean you can be doing things wrong without even knowing about it. A critical part of open source is code review, even if it can be harsh sometimes.
  2. Proponents of privacy and security might err on the side of caution and forego surreptitious proprietary software altogether, a kind of quixotic approach to technology. However, being a “privacy vegan” as I’ve heard it described, isn’t always the best way to go. In reality, a lot of handy software is proprietary, and open source equivalents can be either mediocre or nonexistent. But that’s not always the case. But one thing’s for sure: anyone who insists on 100% open source will usually miss out on features and convenience – creature comforts that are often afforded by commercial software, which is usually proprietary. The relatively clandestine nature of proprietary software (and Software as a Service, or SaaS) can be off-putting at times, and privacy has been eroded in recent years. But open source just doesn’t cut it sometimes.
  1. People who prefer commercial software and dismiss open source might think of it as ersatz software unworthy of their time. It’s true that open source projects can sometimes be a little rough around the edges, but there’s still a lot of open source software worth using.
  1. Open source – odds are that if you’re putting something on GitHub, or viewing someone else’s project, it’s open source. Open source means you can see the source code as opposed to just compiled code. It’s the antithesis of the proprietary model. Source code is like a recipe for a pie, whereas proprietary software/compiled software is like a finished pie. Some people mention how you can’t trust proprietary software as much as open source because bad things could be hidden in it that are hard to detect. Open source is better in that regard, but still not perfect. Creating an open source project, or even open sourcing a previously proprietary project, can help build rapport with clients.
  2. Open source isn’t always about coding and committing to your own GitHub repositories. Sometimes it involves talking with other people to try and figure out complicated issues. Large communities of people power open source.
  3. Now and then, you hear about a company open sourcing a heretofore proprietary project, but it’s usually for older things. For example, Microsoft recently released the source code for DOS, but that’s no longer relevant. Moreover, while some open source projects are exemplary (such as tools for programming or security), many are lackluster, especially in multimedia editing, business, and other productivity software.

Open source evangelists might vehemently deny any flaws, but let’s face it: the user experience of a lot of open source software is sorely lacking compared to commercial alternatives. However, that’s not to say that open source is without merit. Security and privacy are core tenets of open source, and it can be superior to proprietary software in these regards.

Some say open source is more rooted in pragmatism, whereas free libre software is more ideological in nature. But these days, you can use the terms interchangeably and people will get the gist of what you mean.

Some open source developers might be accepting of outside contributions, like pull requests, feature requests, bug reports, and so on. However, others might prefer to release their software as open source but reject any external contributions, perhaps to maintain more autonomy over their project.

  1. License – if you let people use your app, whether free or for money, you will need to include a license. If you use someone else’s code in your project, you will have to be aware of potential licensing issues. For projects on GitHub, most people use one of the following licenses: MIT, BSD, Apache, or GNU GPL. You can make your own license if you want. A license is crucial. If you skim through the licenses (which are freely available online), you can ignore much of the legalese, but there’s one very important thing with these licenses: the caveat emptor disclaimer. Something like “this software is provided AS IS, without warranty.” Otherwise, people can be very demanding even when you’re giving your software away for free. Sometimes, your code can mess up, and you want to make it clear that people are using your software at their own risk.
  2. Sometimes, your software messes up a little. Sometimes, you write code when you’re sleep-deprived, and massive screw-ups happen. Here’s a famous example:
  3. https://github.com/MrMEEE/bumblebee-Old-and-abbandoned/issues/123

Repository – a project in git is called a repository, or repo for short. Some simple programs might only have a single file, like a shell script. But more advanced programs will often span multiple files and directories, so you can keep track of it all by putting everything into a repository. You can have a public or private repo on GitHub, or use your own git server and host your repo there. Some people dislike how Microsoft bought GitHub, and they are moving their repos to other hosts, or even just doing self-hosting. Some other alternatives to GitHub include GitLab and BitBucket, but they are all essentially the same thing: git servers that can host repositories.

  1. Most of my projects are publicly available on GitHub. One of the apps I’ve made is called EZcrypt, which is on GitHub and released under the GNU GPLv3 license. I encourage you to check out my projects. Not only do I have a lot of current projects there, but I have many plans for future things I’ll be making in the future. GitHub profiles are a great online portfolio which can help you stand out among other candidates applying for the same development jobs. The ‘contributions’ section is a good way to gauge how active someone is with programming. Getting a computer science degree by itself isn’t enough, you need to also prove to people that you know how to program outside of a classroom environment. So that’s precisely why I chose to do #100daysofcode.
  2. Private vs. public repos – you can make your repos private or public on GitHub. For more finished projects, you might want to showcase them, so your best apps should be public. For homework assignments, they should almost always be private, so that other students can’t copy what you did. They’d be cheating, and you’d be enabling their cheating. Lastly, unfinished or otherwise bad projects might be best as private repos so they don’t make you look bad. Keep in mind that you can always change whether a repo is private or public.
  3. Markdown – a simple way to make documents with some basic formatting is to use a markup language called markdown. You can have things like headings, bold text, links, and images. It’s an easy way to add flair to a README file. Check out this Markdown cheat sheet to learn it: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Merge conflict – occurs when you merge after you changed the same code that someone else modified, so you have to pick which ones to use. Merge conflicts are frustrating, so a better thing to do is make sure two people aren’t working on the same files or lines of code at the same time.

  1. Issues – Issues on GitHub can be related to adding new features, or fixing things that already exist. Think of it as a public to-do list for an open source project. When you complete or solve the issue, you close it. For example, on one of my repos, I made an issue for a missing favicon. Then I made a favicon for my project and then closed the issue. A favicon is the little icon you see in a web browser tab.
  2. Collaborator – Aside from forks and pull requests, another way to have someone contribute is with adding them as a collaborator, and giving them write access to your repository. You can use organizations or add someone individually. I am testing out code review, but it turns out that someone needs to be a collaborator with write access to a repo to be allowed to participate in code reviews.
  3. GitHub contributions – I have a pretty high number of GitHub contributions so far this year, and it’ll only increase as time goes on. But I’m making rather small apps, and with frequent commits/issues, and more recently, pull requests and code review. But I’m starting to realize that, just like how lines of code isn’t a great measure for software, Github contributions aren’t a great way to measure the worth of a software developer. Quality over quantity.
  4. Fork – if you see someone else’s open source project and want to make changes of your own to it, and you’re not a part of the team allowed to make changes to it directly, you can make a fork, which is your own separate version of it. It’s a separate repository that won’t make changes to the original.
  5. Pull requests – if you fork a project and make changes to it, and then want those changes to be put back into the original repo (not your version of it), you submit a pull request to see if the original project maintainers will accept it. They might not.
  6. On the other hand, people might submit pull requests to your own repositories. But be wary of accepting other people’s code. It’s possible, though not likely, for someone to submit subversive pull requests to your open source project. That’s why you need to make clear guidelines for how people are allowed to submit code, and you always need to audit pull requests before accepting them. Learn to say no. It’s perfectly fine to reject a pull request if you don’t understand what the code does. It could be malicious for all you know.
  7. Furthermore, even if it’s not malicious, it could just introduce new issues. Trusting just any old software developer on the internet is naive. Some people want to do nefarious things, while others are just incompetent. That being said, there are plenty of good developers out there, but a healthy dose of skepticism is good when dealing with pull requests submitted to your project from strangers on the internet.
  8. Technology is more delicate than we’d like to think. I often wonder about all the precarious software we use that is one link click or one pull request acceptance away from being compromised for all (or at least some) of its users. Software developers often overestimate their knowledge of information security.
  9. Contributing to other people’s projects – It can be tough to start contributing to someone else’s project. It might use build tools you’re not familiar with, multiple programming languages, which you’re not equally familiar with, and they might have their own guidelines and stylistic preferences for contributions from other developers. Not only that, but even after reading their code, forking the project, learning the ins and outs of the repo, and then submitting a pull request to address something posted in an issue, it might still get rejected.
  10. That’s a risk because you’re putting a lot of time and effort into something that might not pan out. This is one of the reasons why I am hesitant to get into contributing to other projects, but it’s something you have to do eventually to grow your skills and get out of your comfort zone to learn new things and increase your programming repertoire.
  11. Mirror – if you have your software available for download on your website, you might want to create a mirror. A mirror is another site that hosts the same file. Maybe you’ll put all your program’s files and folders into a compressed .zip archive, and then host it on something like FossHub, which lets you host files that other people can download. Of course, then you have to trust the mirror. Mirrors won’t necessarily be malicious themselves, but they are sometimes the target of attacks to distribute malware. That is why checksum verification is important, so users can make sure the code they download isn’t tampered with. Or you can leave your code on GitHub instead. I think mirrors are a kind of antiquated thing, what with CDNs and free public git repo hosting nowadays, but they’re still around for certain things.
  12. README – a README file contains information about the repo – what the app does, who made it, licenses, how to contribute, code of conduct, contact information, and more. People will see the README when they view your repo’s page on GitHub. When you use someone else’s software, you are supposed to read the README before using it. It will help make it easier if you do. README files are .md files, usually README.md. It stands for Markdown. You can also use a plain text file, like .txt. However, Markdown allows for better formatting.

Open a text editor like VS Code, write some markdown, and then save it as a .md file. README.md is a very important file for GitHub. It lets people see what your repository is all about.

Here are some basic Markdown features:

# 1st level heading

## 2nd level heading

### 3rd level heading

Links:

[This is a link](https://example.com)

Embedding images:

![Free Software Foundation logo](https://static.fsf.org/common/img/logo-new.png)

Bold:

**This text is bold**

Italic:

_this text is italic_

Numbered lists:

1. First item

2. Second item

3. Third item

Technically, you don’t need the write numbers for a numbered list. They can all be 1, if you really want. They will still show up as 1, 2, and 3:

1. First item

1. Second item

1. Third item

You can also have nested lists:

1. Something

2. Something else

1. Nested thing 1

2. Nested thing 2

3. Some other thing

Nested items require 4 spaces.

Unordered lists (bullet points):

– Here are some unordered things

– Another one

– Whatever

Code formatting:

(function(){

alert(“this runs without a name or an invocation”);

}());

You need 4 spaces followed by whatever indentation in the code you want to use. Every line in the code block needs 4 spaces at the beginning.

Also, the above code is an example of an automatically-invoked function expression in JS, which is a cool concept. It’s a function with no name and it doesn’t need to be called because it gets called automatically.

There are more Markdown features, but this should be good enough for beginners.

  1. Aside from a readme, there are other things you might want to add to a repository (but only if it’s a sufficiently-big project, not something tiny that you don’t want to put much time into):
  • Code of conduct – behavioral standards for people who want to be a part of your project. It’s basically just saying “don’t be a jerk” but with 1,000+ words.
  • Contributing – guidelines for people who want to contribute to your project.
  • Issue templates – helps people format issues that they want to create for the project. An issue can be something like a bug, and creating an issue for a repo can be a helpful way of letting developers/maintainers of a repo know that something is a problem and needs to be fixed.
  • Pull request template – a pull request is when someone forks your repo, makes changes, and then wants their changes to be reflected in your original repo. Pull requests, being submitted by people who don’t have direct commit permission to the repo, are often vetted before being accepted, and a template can help make it easier for someone to contribute a pull request in a way that won’t be rejected. If you ignore templates, your contributions aren’t likely to be accepted.

← Previous | Next →

GitHub/Project Management Topic List

Main Topic List

Leave a Reply

Your email address will not be published. Required fields are marked *