From 02c40d5e1f446bcfeca52243142febab9807473d Mon Sep 17 00:00:00 2001 From: Razvan Deaconescu Date: Mon, 25 Dec 2023 23:39:47 +0200 Subject: [PATCH] Update contributing guides Add section about slides. Add information on doing commits (inspired from Operating Systems). Signed-off-by: Razvan Deaconescu --- CONTRIBUTING.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7586cb..8b51072 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ Some good first steps and best practices when using Git are explained here: * the Git Immersion tutorial: * the Atlassian tutorial: -* this blog post on the ROSEdu Techblog: +* this blog post on the `ROSEdu Techblog`: ## Language @@ -34,6 +34,19 @@ Use phrases like "find the flag", "run this command", "download the tool". Use [draw.io](https://app.diagrams.net/) to create diagrams. If using external images / diagram, make sure they use a CC BY-SA license and give credits (mention author and / or add link to the image source). +## Slides + +Slides are to be written in Markdown, using [`reveal-md`](https://github.com/webpro/reveal-md), itself based on [`reveal-js`](https://revealjs.com/). +Use `reveal-md` and `reveal-js` specifics to split information in slides. +Aim to make slides attractive, sleek and simple to follow. + +Images and diagrams would ideally be animated on slides. +Aim to use `reveal.js` features to animate drawing of diagrams. + +If `reveal.js` drawing is difficult, use [draw.io](https://app.diagrams.net/) to create diagrams. +Ideally you would "animate" those diagrams by creating multiple incremental versions of the diagram and adding each to a slide; +when browsing slides pieces of these diagrams will "appear" and complete the final image, rendering an animation-like effect. + ## Issues When opening an issue, please clearly state the problem. @@ -58,8 +71,47 @@ If there are multiple commits belonging to a given change, please squash the com Also make sure one pull request covers only **one** topic. +### Commits + +Before making a commit, configure your name and email locally using: + +```bash +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" +``` + +Then make sure the email you've just configured corresponds to the one you have [set on GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). + +After this, make your changes, `git add` them and then commit them using `git commit -s`. +Always sign your commits using the `-s` / `--signoff` arguments to `git commit`. +This will add the following line at the end of the commit message: + +```text +Signed-off-by: Your Name +``` + +Notice that the details above are the name and email that you configured earlier. + +Now the `git commit` command will open your default editor and ask you to write a commit message. +Prefix each commit message title with the chapter it belongs to: `software-stack`, `data`, `compute`, `io`, `app-interact` and the component: `lecture` / `lab`. +An example of a prefix is `compute/lab:`. +Following the prefix, write a short and expressive title on the first line. Use commit messages with verbs at imperative mood: "Add README", "Update contents", "Introduce feature". -Prefix each commit message with the chapter it belongs to: `software-stack`, `data`, `compute`, `io`, `app-interact`. + +Leave an empty line, then add a relevant description of the changes made in that commit. +This description should include why that change is needed (fixes a bug, improves something that was inefficient, etc.). +Wrap the lines of this description to 75 characters. How a good commit message should look like: +Below is an example of a good commit message: + +```text +data/lab: Fix Makefile `CFLAGS` error + +`CFLAGS` was incorrectly set to optimise the code to the `-O3` level. This +caused the function `vulnerable_func()` to be inlined into the caller +`main()`, making it impossible to overwrite `main()`'s return address with +that of `vulnerable_func()`. This commit fixes the issue by forcing the +compiler to not optimise the code by replacing `-O3` with `-O0` in `CFLAGS` -The use of `-s` / `--signoff` when creating a commit is optional, but strongly recommended. +Signed-off-by: Your Name +```