1. Project management and documentation#
Goal :
- work through a git tutorial
- use git to build a personal site in the class archive describing you.
- test and apply project management principles all along the class.
- document your learning path for this module.
- Evaluate your work
Documentation#
To write our documentation, we’re going to use Gitlab. Gitlab is similar to a server (or cloud) where you can put your files.
Note: I am on Ubuntu 22.04, the steps could be different for people on Windows, on MacOS or on older versions of Ubuntu.
SSH Key#
First step is to establish a secure connection between the client (us) and our repository on the server (Gitlab). SSH stands for Secure Shell Protocol. There is a public key and a private key, the private key is kept on the client side and should not be disclosed and the public key is disclosed with the server (Gitlab here). The SSH key is generated by a cryptographic algorithm (rsa, dsa, ecdsa, etc).
Create a SSH key:#
- In your terminal, write
ssh-keygen -t ecdsa -C "YOUR_EMAIL" -P ""
Note : You can use others algorithms to encrypt the key, like dsa | ecdsa-sk | ed25519 | ed25519-sk | rsa
Your terminal will write this :
Generating public/private ecdsa key pair.
Enter file in which to save the key (/home/emily/.ssh/id_ecdsa):
-
Type enter if you don’t have any SSH key, or choose another directory if you already have a key.
Your terminal will write this :Your identification has been saved in /home/user/.ssh/key Your public key has been saved in /home/user/.ssh/key.pub -
Go to the repository indicated by the terminal
Note : If you don’t see the .ssh directory, click on “see all hidden files” - Recover the key in the file “key”.pub
- Add this key to gitlab.com -> preferences -> SSH keys
Clone the repository#
Second step is to clone our repository. This allows to have a “copy” of the server files on our computer.
| First Method: Terminal Mode | Second Method: VSCode |
|---|---|
- Go into the repository you want to clone on Gitlab, click on “Clone” button :  - Copy the git@gitlab.com:repo. - In the terminal, write git clone <git@gitlab.com>:gitlab-tests/sample-project.git (with the link copied in the step before) |
- Install the Gitlab extension - Clone the repository : Press on Control + Shift + P and write Git: Clone, then select Clone from Gitlab and find the repository you want to clone. |
Gitlab#
Git is a distributed version control system. It means that Git tracks changes between a server and one or multiples clients. Gitlab uses Git to track changes between Gitlab and your computer.
How to commit modifications to Gitlab#
First, you need to configure yourname and email.
git config --global user.name "Your name"
git config --global user.email "Your email-address"
They are two methods:
| First Method: Terminal Mode | Second Method: VSCode |
|---|---|
git add -A" : prepare all your files to be staged git commit -m "modifications made" : stage your changes git push : push the branch to the remote |
Go to this icon :  Enter a message in the box and click on commit.  |
Mkdocs#
Mkdocs is a static site generator (used in this site). On Ubuntu, you can install it with the command sudo apt install mkdocs.
To preview your website, you can use the command mkdocs serve.
I had an error : Error: Unrecognised theme name: 'spacelab'. The available installed themes are: mkdocs, readthedocs. I looked on GitHub and I installed mkdocs-bootswatch with the following command line : sudo apt install mkdocs-bootswatch. I used the theme cyborg.
After a while, I had an error, apparently related to me installing docker. The error was AttributeError: module 'jinja2' has no attribute 'contextfilter'.
To fix it, I wrote pip install jinja2==3.0.3
Markdown#
Markdown is the language used for this website and used by Mkdocs. It’s very easy to write in Markdown.
CheatSheet#
| Markdown | Description |
|---|---|
| Title | # H1 ## H2 ### H3 |
| Italic | *italic* |
| Bold | **bold** |
| Image |  |
There is more in this cheatsheet.
CSS#
CSS is used to define the styles of your site (customize your site). I made a new directory called “css” and a new file in the directory called “extra.css” and changed the color of the background and the headers with CSS.
At the end of my mkdocs.yml file, I added
extra_css:
- css/extra.css
The file extra.css will override the existing css. Then you can customize as much as you want. For example, if you want to change the color of the first header, you can write:
h1 {
color: #3982b8;
font-size: 32px;
}
Issues#
We use issues to track our progress in each module.
How to import issues#
I added this little section because I had some difficulties to understand how to import issues. You need to go Evaluation Module and then download the files. When you downloaded the files you go to your issues tab on gitlab. Then click on :
ImageMagick#
To keep images size low, we can use ImageMagick. We can install it with the command sudo apt install imagemagick.
Some Useful Commands#
| Command | Description |
|---|---|
mogrify -format "format1" *.format2 |
Modify all the files with the format2 to the format1 (png, jpeg, jpg, pdf) |
magick convert *.format1 file |
Convert the file to format1 |
magick file1.png -quality x% file2.png |
Lower the quality of file1.png by x% and save it to file2.png |
Project Management#
In class, we talked about differents principles. We saw 6 differents principles/laws but I’m going to use As-You-Work Documentation, by taking pictures and videos while I work. I’m also going to use Triage and Spiral Development because I’m used to these principles in my bachelor, where I need to code a lot of projects in groups. I don’t like Supply-side Management because I tend to be distracted, so when I use time management I always end up doing one task in two hours, I don’t focus on the tasks left (Parkinson’s Law is a good explanation of this).
As-You-Work Documentation#
We need to document everything that we do while we work. It help us to memorise the steps we took to achieve (or not) the goal. It is also important to write the issues we had and what we have done to overcome these issues.
Spiral development#
Write a draft of a project even if it’s not perfect and then add versions more and more refined.
Modular and Hierarchical planning#
Seperate the parts of the projects in differents small tasks and organise them in a logic order (the most important first).
Triage#
Prioritise the critical parts of a project.
Supply-Side Time Management#
Organise the project by time and not by tasks.
Parkinson’s Law#
The duration of any task will take the time you alloted to it.
Hofstadter’s Law#
It always takes longer than expected.