Your first GitHub fork
by, 08-01-2017 at 11:59 (1135 Views)
The introductory blog post tried to sum up the advantages of GitHub for your thinBasic project storage and publishing.
Let's leave the cold theory and embrace some practical example! This post will describe the basic workflow for founding a new thinBasic project at GitHub.
Grab the fork
Multiple times, across the original article, I mentioned the term fork. As it might not be obvious, let's have a look at what does it mean to create fork of GitHub repository.
Everybody can create a project and GitHub, and everybody, unless you disable it in settings, can base his further work on it.
While the basic collaboration could be setup via multiple code branches inside single repository, it is wiser to adopt the fork approach. It helps you to isolate your solution better if needed, and avoids accidents with global impact.
Forking a repository means creating a copy of the original one, copy which is still linked to the original. You may decide to not pick the advantage this connection offers anytime later, but you will mostly benefit from it, especially on the beginning.
I presented a GitHub project template for thinBasic in the introduction. It contains some initial setup. Imagine, that in the future, some further setup will be needed for thinBasic GitHub integration - for example, adding information about repository language as thinBasic, once it will be possible.
In case you would have a completely separate repository, you would have to do that manually. If you base your project as fork of GitHub project template, you can easily resync your code base via so called rebase. I will dedicate more explanation to this concept in some further articles, for now please understand that it is an easy way to update your project, performed via single command.
Creating new project
Enough talk, let's get practical:
- head to GitHub.com and log in
- go to thinBasic official GitHub and open github-project-template
- in the top-right corner, click on fork button and confirm
Once you confirm, you will be taken to fork made in your repository. It will share the same name as original, here is example for my case.
- the repository name is the same as the original
- the description still talks about this being an template
As we will want to use it for storage of our custom solution, we need to address these somehow.
For both, there is an easy way out. Let's start with name change.
To change the project name, pick the Settings tab. There is a convenient option of Rename repository. For demonstrational purposes, I will upload my interactive PF 2017 there, so I will call my repository pf-2017 and confirm the change.
To change the project description, I hit the Code tab, to get back to the default view. In the code listing, please click the README.md.
Once the page reloads, search for the icon of pencil to edit the file directly in browser.
The view will change to source editation. The README.md is "coded" with markdown syntax. If you prefer some WYSIWYG, you may try online tool, such as StackEdit.io. Once you are satisfied with your project description, you are about to make your first commit!
Commit is a batch of changes, which appears in the repository. It is good to think about good commit message, which describes the change.
I personally follow this convention:
- "fix: <bug description>"
- "feat: <feature description>"
- "refactor: <refactoring change explained>"
- "docs: <what was added>"
For this case, we could go with docs, as we are not touching code, but its documentation. So I would scroll down, fill in "docs: readme adjustment to match the project" and hit Commit changes.
You should see the change immediately, and even when you switch back to Code tab, the repository will be now described in its lower part with adjusted explanation.
There might be left the original description of the template on the top, but that is not bound to code, just GitHub setting. You may edit it via dedicated button.
Adding your code
Now its time to add your own code to the repository. While it can be done completely via the online interface, I would recommend to use GitHub for Windows from this point on.
Once installed, it nicely integrates with the GitHub online interface - to clone the changes we just did to local hard drive, hit the Clone or download button, and choose Open in desktop.
Browser will ask you whether you want to open it with GitHub application, please allow that.
You will be prompted where should be the repository downloaded. I recommend you to create something like Repos, directory on your data hard drive, and choose that one.
New directory, named as your repository, will be added inside Repos then. It should contain 3 files we know, and you may also see hidden .git folder, which is used for some local tracking.
Head to the directory, and place some code there. In my case, it were the two files. I tend to place tbasicu in units folder, and main code in the root, where README.md is.
Once you switch back to the GitHub for Windows application, you can do 3 simple steps.
- Click the Changes button, indicated by blue arrow
- Confirm visually there are files you added, indicated by green arrow
- Fill in your commit message, indicated by orange arrow
The commit message has the same purpose as the one we filled in while editing README.md - give information about the change you did.
Once this is done, please click Commit to master. Doing this will update the main, master branch of your code. When you hit the History button on the top of GitHub for Windows GUI, you will see two commits. The original one, where we edited the README.md and the one you just did.
If you click the first commit, you will notice you can easily review the changes. Removed lines are in red and added ones in green colour.
To make the changes visible online, please just hit the Sync button in the top right corner of the GUI. You can verify the success by going to your browser, and refreshing your repository page.
You learned how to create your new thinBasic project by forking the GitHub project template, adjusting the name and README.md information and finally, adding some of your own code.
With this knowledge, you can start versioning your code at GitHub. Each new change can be just commited to master and synced, giving you easy review of the changes over time.
But there is more to GitHub, stay tuned!