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.
- 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.
- 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:
- the gittutorial
- the atlassian tutorials, particularly setting up a repository, saving changes, undoing changes, syncing and using branches.
- an interactive tutorial by github
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 theremote
repository. By defaultremote
is set toorigin
(i.e. the repository you cloned). git fetch <remote> <branch>
- Download the
branch
from theremote
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 bygit 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 ifbranch
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