Source code management

What is "source code management" and why is it usefull ?

Source control (or version control) is the practice of tracking and managing changes to code. Source control management (SCM) systems provide a running history of code development and help to resolve conflicts when merging contributions from multiple sources.

What are the alternatives ?

Git is by far the most popular but there are alternatives. I've been working with other tools, like SVN, VSS and TFS/TFVC. SVN is a centralized version control system (VCS) while Git is distributed, which means that every developer has a copy of the repository on their local computers. This is not the case in Subversion, which relies on a single server to handle collaboration. Team Foundation Version Control (TFVC) is a version control system from Microsoft. TFVS now relies on GIT internaly and offers many extended features for SW management

GIT - how does it work ?

There are many tutorials and I dont'want to create another one. Let's focus on the main concepts first:

• repository: the purpose of Git is to manage a project, or a set of files, as they change over time. GIT stores this information in a data structure called a repository. The GIT repository is stored in the same directory as the project itself, in a subdirectory called .git.
• local vs remote: local means... local, i.e on your computer. Remote meaans.. somewhere else. I guess you feel it is a great idea to keep your stuff remote in case your computer is stolen or broken
• add: adding things to your repository means you start tracking them.. locally. It helps to backtrack when somethings goes wrong. It does not solve the computer stolen issue and it does not help you to work with others. A newly created file is not automaticaly added to the GIT repo, you have to ask GIT explicetely (add myfile or add . to add all files)
• commit: commiting things is like writing an entry in the big book of your achievements, along with a copy of your piece of art. When you commit, GIT will track down all changes (since the most recent commit) but only for files under its supervision (do not forget to "add" them)
• master and branchesif you work alone, sequentialy, without anybody reviewing your stuff or contributing, without delivering anything to any customer unless everything is complete and assuming no customer feedback will be considered.. "branches" is a concept you could ignore. Otherwise, you have to take it into account.A common way to use Git branching is to maintain one “main” or “trunk” branch and create new branches to implement new features. Often the default Git branch, master, is used as the main branch.Ideally, in this pattern, the master branch is always in a releaseable state. Other branches will contain half-finished work, new features, and so on.
• clone: cloning a repository means getting the most up to date copy in order to work locally on it
• push: pushing changes means bringing back to the repository the commited changes, in order to make them available for other developpers
• pull: it is similar to a push but in the opposite direction, when you want to update your local copy with the changes pushed by others.

The following schema is a pretty good summary on how information is flowing between your local computer(in green) and the remote repository (in blue). See this site for a more detailed tutorial.

How to setup Git

The first step is to install it on your computer. On Linux, just type "sudo apt-get install git". Once Git is installed, start your configuration...

And then check it...

What is GitLab ?

GitLab is a web-based Git-repository manager providing wiki, issue-tracking and CI/CD pipeline features, using an open-source license, developed by GitLab Inc. Using GitLab, you can store your code, keep an history, organize code reviews, manage branches and create a pipeline that will perform all the required operations to transform your source code into a great application

How to setup GitLab

There is a shared GitLab repository for Fab Academy students. Since I had already a GitLab repo, I prefered to continue using my own setup and to use the Fab Cloud only for weekly deliveries. It gives me more freedom if I want to try any new GitLab feature.

There are two options when you want to start with GitLab: the first one is to setup your own, self hosted environment (i.e "on premise") and the second one is to leverage existing cloud-based environment. Fab Cloud and my own environments are hosted on the Cloud. Then you have to create a projet (Fab Academy staff did it for you) and decide whether the project is public (anybody can see it) or private (only for people you give access to).

The last step is to configure your local computer (running Git) to communicate with your cloud-hosted project. As per Git point of view, your project within GitLab is a "Remote repository".

From security point of view, there are two options: the first one is to secure the communication channel using HTTPS, the second one it to rely on SSH and a RSA key. The SSH way has the advantage that you don't have to enter your credentials again and again but it requires some configuration. Basically, you have to generate a RSA key (asymetric encryption key) on your local computer (Note: do NOT sudo the commands since the folder where the RSA key is stored is user specific) and then copy the public portion of the key on the GitLab server. Here it how it looks like:

Using GitLab to manage your tasks

GitLab is not only about source control. There are other features, such as a Kanban/SCRUM subsystem. Here is how it works: in GitLab terms, everything is an "Issue" (similar to JIRA, another SW management system). You may consider that an "Issue" is "Something you have to do". You can define "milestones" (like you would declare "sprints" in a SCRUM system) and attach your "issues" to those "milestones" Here is how my "Fab Academy journey" looks like:

There is another view, based on a Kanban approach. Each "issue" has a status (at least something like "Opened/Todo/Working on it/Done") and there is a summary board. The board emcompass all milestones Here is how it looks like:

GIT Cheat sheet Github vs GitLab

Web site development

What does it mean to design a "static" web site ?

In order to understand what "static" means, we have to go back in the www history and see how the first web site were designed. On the right side, there a web browser. Its role is to request a piece of information from the server located on the left side. That piece of information is typically a web page (i.e HTML code) or an image, stored as a file. The file flows back to the browser and the browser will "interpret" it in order to present a nice view to the user. Each time there is a reference to another piece of information (a link to an image embedded in a HTML file for example), the browser will initiate another call to get the content

Once the page is displayed to the user, he may decide to click on any link on the page and the process restarts (call the server to get the required piece of information, crunch the entire page again and refresh the screen.

But what if we would like to display something dynamic on a web page, such as the current temperature in Quebec City (btw, today it is -27 degrees Celsius. Yes, MINUS ! ). Then we need some kind of programming on the server side to create the HTML code dynamicaly, on request, only when a browser is requesting it.

There another issue poping out. What is we want to create some dynamic behaviour on the browser side. What if we want to display menu items (like the ones shown currently on the left part of this screen (or on the top if you are on a mobile). Then .. we need some other kind of programming embedded in the web page. That's scripting !

For Fab Academy, we have been asked to create a static web site and I was quite surprised initialy. It means you cannot leverage CMS (content management system) like WordPress, Drupal, .. that makes you life way more easy. You can focus on the content and not that much on the HTML syntax. But, anyhow, challenge accepted !

"Bracket", a nice tool to code de static web site ?

Ok, I need a tool. Notepad, nano, even VIM .. could make it but you dont' have to be so hard on yourself. We can, at least, select a tool that manages HTML syntax properly. I tried Bracket (I'm on Linux). The biggest advantage I see is its preview mode. You code wihtin Brackets and the HTML is more or less directly interpreted in a Chrome instance you can see in background or on another monitor. It helps a lot to see the impact of the fancy HTML parameters. Backets helps a lot to structure your code, at least to indent it properly.

"Plain HTML", it looks like "plain"...

Great code does not mean great UI.. My first Bracket-edited web page looks ugly.

Let's make it more attractive. CSS (Cascade Style Sheet) have been invented years ago to help to solve that problem: programmers have not that much talent for design ! We should delegate the design part to experts in graphics. But... I don't want them to play in my code ! This will for sure break my beautifull script.. Sure, that's why CSS are packaged separately and applied at display time. Style can be embedded in your HTML page or packaged in other file. Here is a very simple example. It helps to maintain the same look and feel from one page to the other.

tbd

"Bootstrap framework" + "template": how to use it to get something clean but still static ?

HTML + CSS, a good starting point... But there is a way to do more. The idea is to use a framework named Bootstrap and to leverage existing templates designed by people with much more talent in graphics I will ever have.

My starting point for this site is the folowing template.

Once downloaded, have a look to the HTML code. I changed the set of colors (in the CSS) and I updated the list of links. By default, this is a "one page" template where everything resides in the same HTML file. Fab Academy journey is long enough to require multiple pages, typicaly one per week. Within your main page, instead of refering to local items (using #zzz tag), just refer to external pages

On the right side of the page, my intent was to list the course topics, with a title and a funny image. The best way to achieve this was to leverage part of another template named "Portofolio item".That template implements a Bootstrap object named card. Card s can be grouped in card deck and Bootstrap takes care of the all the non-funny work to support various screen sizes and resolutions

I applied the same design to all other pages, one per week but with a single column.

Web site deployment

Once the web site is ready on my computer, I have to push it to the remote repository (the Fab Cloud). This is quite simple (git add ., git commit..., git push) but then I faced some problems. Here is the message I got in my mailbox

On the bottom part of the message, there is a copy of the log, with some attempt to explain why things went wrong. I did not copy the detailed log here since it contains some sensitive info like users and file locations but here is what I learned.

Fab Cloud staff tried to help students and they provided a tool and a mechanism to publish static web site content and to move it to the right final location (which is http://fabacademy.org/2019/labs/echofab/students/philippe.libioulle/ in my case), so it could be visible for local and regional instructor and for other students as well. On the my Fab Cloud repository page, here is what is explained:

Mkdocs is a tool that helps to generate a static web site. Sadly, I prefered another one. This is still ok, since staff says I just have to "delete everything in the repository" and push my content. Right ? NO ! .. and here is why

It means the staff has create a pipeline (a set of jobs to perform each time updated content is pushed) and the pipeline is designed to deploy content built using Mkdocs. I restored the initial content and then it ran smoothly... at first sight

The pipeline runs two jobs: the first one crunches the content and build a set of HTML pages and the second one should nove it to the final location. But it does not...and I don't have a clue why since it is an "external" job I cannot see anything

After some readings, I figured out that the trick was in the .gitlab-ci.yml file. The default one provided by Fab Academy staff was tuned to work with Mkdocs. I updated it with the following content and.. it works like a charm !

#1 - Git

I installed it on my computer, configured it with my credentials and created my repository

#2 - GitLab

I had already my own GitLab repository. I generated a RSA key and I configured it within GitLab. I did it twice, one for my own GitLab repo and anotherfor the Fab Cloud. I cloned Fab Cloud project and I started creating the web site.

#3 - Bracket

I installed it on my computer and used it to create my web site.

#4 - My web site developped using Boostrap

I improved my web site look and feel using Bootstrap and Bootstrap templates. I uploaded my web site to the Fab Cloud (weeks #1 and #2, and my biography).

Impact on my capstone project

While I was reading on GitLab, I discovered a tool to manage tasks and I put all tasks related to my capstone project in my GitLab (not the Fab Cloud one)

My capstone project