3. Tutorials

3.1. Using Javascript

Since we are going to develop a single-page app, a considerable part of the code will be targeted to and executed by web browsers, meaning: Javascript.

For ease of learning and to agree on something to get started, we settled on using plain javascript ES6 rather than languages such as Elm.

Here are some links to learn Javascript, particularly the more recent ES6 specification, that makes syntax orders of magnitude more convenient.

  • https://javascript.info/
    It seems to cover the essentials. You can really skim through the entire guide, since you will a find a lot of similarities with any non restrictive scripting language, much like python.
  • https://babeljs.io/learn-es2015/
    This guide puts the emphasis on what is new with the ES6 specification (previously known as ES2015).
    While not all of it is relevant, you should pay close attention to new features that make writing js - dare I say - beautiful.
    Most notably:
    • Arrow functions.
    • Destructuring and Spread operator.
    • Classes.
    • Let & Const declaration, that should be preferred to var.

3.1.1. Style conventions

TODO: - describe the code style we aim at. - one part dedicated to syntax. - the other dedicated to how we organize code, structural choices.

3.2. Using git

We will give a short list of usefull git commands in this section. For a more complete introduction to git, please refer to the following links:

3.2.1. Golden rules

  • The branch master is here only for working and tested stuff. Never commit to it directly but instead pull commits from other branches to it once they make a consistent group.
  • Never alter commits that have been pushed to a public (remote) repository.

3.2.2. Cheatsheet

git clone <repo>
Create a local copy of the distant repository repo.
git add <file>
Add a file to the next commit, this is called staging a file.
git commit -m "<message>"
Commit the staged files with the specified message (instead of launching the editor).
git push <remote> <branch>
Push branch to the remote repository. By default remote is set to origin (i.e. the repository you cloned).
git fetch <remote> <branch>
Download the branch from the remote repository.
git merge <branch>
Combine branch onto the current branch. If there are conflicts they will be explained. It will fast-forward if possible.
git pull <remote> <branch>
Equivalent to git fetch followed by git merge.
git checkout <file>
Revert file in the working directory to it’s last commited state.
git checkout <branch>
Switch the working directory to branch. Uncommited changes in the working directory are kept. It will transparently create a new local tracking branch if branch is a remote branch.

3.2.3. Using branches

Branches are used to separate independant parts of the work to identify what is related and what is not. Once the work is done the branch should be merged back into the master. A branch is just a named reference to a commit (which is the HEAD of the branch) so it’s really lightweight and should be abused.

Say you want to work on something new called feature1. First you have to check out the branch you want to fork from (probably master) with git checkout master, then create the branch with git branch feature1. You could also use git checkout -b feature1 instead which will additionnaly checkout the branch (as you probably want to work on it right away).

Now the branch is local, you might want to push it upstream. To do it, use git push -u origin feature1. If you want to change the upstream name of the branch, use git push -u origin feature1:better-name.

If you want to work on a branch that already exists remotely but not locally, you want to create a local branch that tracks the remote branch with git branch -t local_feature1 origin/feature1. But most of the time you want the branch to have the same name and there is a shortcut for that: git checkout feature1 will do exactely what you want (create a local tracking branch) and check it out.

Now that some work is done, you want to merge back the feature1 branch onto master. To do that, checkout master with git checkout master, merge the branch with git merge --no-ff feature1, resolve the conflicts if there are any, then git commit and finally push your changes with git push origin master.

If you are sure that the branch is not going to be used anymore you can delete it (it just deletes the reference). To delete the local branch type git branch -d feature1 (or -D if it wasn’t merged, but careful you will loose the commits), to delete the remote branch, use git push origin :feature1. If the branch is not going to be used anymore but you feel it was important enough to keep track of it, you can tag it just before deleting it with git tag archiving-name feature1. Names can contain slashs so an appropriate name for the tag might be dead/feature1.

3.2.4. How to write good commit messages

TODO: magic messages