Let's play a game with kids. Time for some computer science without computers.
Polska wersja tutaj
We usually spend summer with my family in Poland. It takes some effort to get seven kids aged 4-10 to play together and without tablets. Last year I prepared this game for children and called it "Dancing Robots".
The goal of the game is to engage a number of skills to prepare a dance and then to dance it. Children start by taking blocks with instructions and then assembling them into a choreography.
I have already published it before in Polish on my Breadcentric account. This time however I have translated it and added a couple tiles. Also, I have prepared a source-controlled version licensed as Creative Commons (CC BY-SA 4.0) for all to use and contribute to. Both source control and Creative Commons has been explained below.
The game is available here: https://github.com/kurykodowe/dancing-robots - just download a pdf file with the game, print it and have fun.
All the instructions are available in the README.md file: https://github.com/kurykodowe/dancing-robots/blob/master/README.md
Follow the instructions provided and have fun! We spent about 30 minutes playing together before the kids got bored.
I would love to see contributions to this project, especially other language versions. If you would like to add something to it, have a read of README for directions. Also the below explanation of what a source control is may help. Finally, feel free to ask questions in the comments. I am aware that the whole technical side of it can be a bit scary. If you would like to contribute to the project, leave me a comment and I will be very happy to help. It will also be an opportunity to prepare a post about helping open source projects.
What is source control?
During preparation of a project and then during it's maintenance and further development, a lot is changing. With software it's mainly text files with code, configuration and data. Every change in behaviour requires changes in those files and sometimes many of those change at the same time. When teams work on a given project, their members can contribute in different areas, therefore it would be nice to have a way of storing not only the content of the files but also a description of changes applied. It would be nice to have a private space to work on one's changes without others interfering with it or overwriting your changes. Once done, a way to merge the private changes would be excellent. And then when a complete set of requirements is delivered, it would be nice to mark that state in some way to be able to refer to it later, for instance when someone working in an old version observes a problem, so that we can trace it down and verify which versions are affected and require a change.
That is what source control gives us. There are many types of them, some free (many open source), some paid for, some centralized and some distributed.
- free - as in available for no charge, sometimes for both personal and commercial use, sometimes for personal only
- open source - project is distributed as a tool available for running and together with all the code from which it could be built. Most often it cannot be closed-sourced just like that and if it's being used by a company, it has to provide information on that. Even more often project leaders accept and encourage contributions from people not involved in the project. Some version controls provide ways to deliver such a change for project developers to incorporate it in their creation
- centralized system* - a type of a system where there is some central authority that holds the one and only truth. For source control solutions such an authority needs to exist to record a change
- distributed system - a type of a system in which each node is in some way independent and provides a certain level of operability. There may be a central node that is used to exchange information and to hold the eventual version of the data, but there may be more than one or each node may agree on data consistency with each other
I tend to use git nowadays. Git is a system which is distributed and open source. It has been created by Linus Torvalds, a guy known by some as the one who created Linux operating system.
It's easy to get started with git (once it's installed). Let's say that I want to create a source controlled repository with a program that will write "Hello". Let's say I want to write the program in a programming language called Python. The code looks like this:
print("Hello!")
Very complicated, I know. I will not be getting into details in terms of explaining what all those complicated commands mean. Python let's me run this as a command in it's interpreter (a tool that takes what I write as an input and tries to execute it):
Awesome! Let's create a repository for that. I will need a folder on my computer:
As you can see I prefer working with text and not windows and a mouse. Most tasks I perform are simple enough that they are so quick to complete and clicking would be more time consuming. One learns the text commands with time. Sometimes I prefer tools with a user interface to look at and to click in if it is more handy.
We have created folder hello (mkdir command), went into it (cd command) and then displayed it's content (ls -la command) which contains nothing since we have just created it. Element . represents current directory hello and .. represents the parent directory dev from which we came here. It isn't really important for us here. What is important is that we want a source-controlled repository:
Now you can see a .git folder inside hello. A dot at the beginning of a file/folder name in Linux (which I happen to be using) is a way of making it hidden. If I skip parameters from the ls command, I'll see:
Can you see it? Nothing.
Let's continue. Our repository is empty, and we'll need our program there. Let's prepare a file for it. I will use a text editor called vim to put the content in it. We will call the file hello.py. Command cat will print out the content of the file:
Nice. Is it under source control? Nope. The reason is because we need to declare the file source-controlled. git status shows the status of the project compared to a previous persisted state:
Git can provide some helpful advice like here: we need to use git add:
Now we need to save the current change (which is adding a new file) to git. We will do it using git commit with a message "Added hello.py":
git status no longer prints our file as a new one - it does say we're on branch master (let's just say it is the main line of code changes) and then git log lists our first commit. But hey, we forgot to run it, let's see how it works:
Oh dear! I cannot type. Let's fix it:
Much better. Let's commit the changes in git:
Now you can see that we have two changes in our history.
Let's now say that this code is extremely useful and I should share it with the world. To do that I can use a git repository available publicly. There's a couple services that let us do that and I'll stick with https://github.com for now. We'll need to create a repository there. I've logged in, went to https://github.com/new and filled in a form:
The next thing I saw was pretty handy, instructions for the most common cases:
Let's quickly recap what we have: there is a git repository locally on my computer and some git repository somewhere out there. They don't know anything about each other. The commands provided enable a couple scenarios, such as using the remote repository to begin work locally or marking a remote repository as the one I want to send changes to. I want the latter.
I followed the instructions and presto:
git push is a command that sends local changes to a remote repository.
Now let's go to https://github.com/kurykodowe/hello and we will see:
Github is more than just a remote repository others can get your code from. Others can contribute to the project and here they are given such chance. To help them a little bit, we can add some info about a project. This is normally done in a file called README.md. md stands for Markdown which is a text file format that adds a bit of formatting to the text (FUNFACT: This text has been written using Markdown as well). In the screenshot above you can see that we can use the webpage to add that file. I'll use that and insert:
# hello
This project is an extremely useful utility printing "Hello".
Feel free to contribute.
This is what we get:
We're almost done. One problem is the difference between the initial requirement: print "Hello", and the outcome of the program: printing "Hello!". As I've mentioned, Github lets us do many things. Let's report an issue using a link on top of the repository page:
You can view the issue description here: https://github.com/kurykodowe/hello/issues/1 (now if you click it, it will not look exactly same as above; spoiler alert: we will fix it).
As an author of a very useful utility I cannot stand having a bug in it. Let's fix it.
Obviously, this is a ridiculously small project so I could just fix it as before and commit it, but let's do it as if it was a huge project with multiple people working on it at the same time. We will do the following:
- fetch the most recent code
- create a branch to fix the issue on
- fix the issue
- raise a pull request (we'll cover this in a bit)
- merge the branch to master
We need to fetch the code because we made changes to it when we added a readme. Just look:
Before git pull we had one file, after we have two. Even the history changed:
Now we need to create a branch fix-wrong-printout using command git checkout -b fix-wrong-printout and fix the code:
Now all that's left is to send the fix for a review and merge:
Now we can have a look on GitHub and we can see two branches:
We can also create a pull request. A pull request is a means of saying: hey, here's a branch, I made stuff there, could someone check it and merge to master? Some people have write access to the repository, others don't. The ones without it can ask to merge code from their branches and this is what pull requests are for.
This is a moment where you should ask me: Wait a minute, how can one without write access write to a branch? The answer is quite simple: GitHub allows forking the repositories. A fork is a clone of a given repository. Everyone can create a fork and read from it, create a branch, commit changes to it and raise a pull request from that branch into original repository's master. I haven't done it here because I am a lazy bastard.
Let's create a pull request:
We can view the changes:
In the Issue view we can see that I have raised a pull request:
GitHub knows I addressed the issue because I used #1 which is a way to refer to an issue with number 1. This is how it associated the commit and the pull request with the issue. I'll merge the change using a button at the bottom of the page:
After merging I've been given an option to delete the branch and so I have done (on GitHub, it's still available locally). Merging the pull request automatically closed the issue.
Let's fetch the changes locally. I will check out the master branch and pull the changes with option --prune that will remove no longer existing branches locally:
That would be enough to show some basic features of git source control.
I know I'm not a wonderful explainer. LaunchSchool are professionals that have released their book about git and github. I would recommend having a look at it.
You can also learn more using resources from the project itself, such as the book "Pro Git" available on-line, licensed under Creative Commons Attribution Non Commercial Share Alike 3.0 license. The book describes how to install the software as well
What is Creative Commons?
This will be short, I promise. It's just about the way we share content. Sometimes the author would like a specific set of rules that the user of her or his creation should comply with. It's called a license. If there is no license attached to that thing, the rules are unclear, really - someone has shared the content but hasn't set out the rules. It might be determined by the platform on which the content got published, but sometimes it isn't.
Within the whole subject there is a set of licenses that serve the purpose of stimulating sharing of things. Such is the case with open source software, but it also applies to non-software copyrighted creations such as books, games, music etc. Creative Commons is a non-profit organization that provides a set of licenses that one can use to set out which rights are protected and which are waived. More or less. I have shared the game under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) which means you can share the game as long as you provide the license information and the author. You can also modify it, but you have to inform about it and still share it with the same license.
Interestingly, our hello project has no license. I will add one now. GitHub provides a selection of licenses to look through and choose from. The general assumption is that the license file is called LICENSE. I have selected The Unilicense which pretty much means this project belongs to the Public Domain.
The end
That's about it. If you have any questions or remarks, leave a comment.