diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6f4f2be --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +# Prerequisite Checklist + + + +- [ ] Read the [contribution guidelines](https://github.com/open-education-hub/ccas-internal/blob/main/CONTRIBUTING.md#pull-requests) regarding submitting new changes to the project; +- [ ] Tested your changes against relevant architectures and platforms; +- [ ] Updated relevant documentation (if needed). + +## Description of changes + + diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index b66a7f7..9e25a1f 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -3,7 +3,7 @@ name: Linter Actions Workflow on: pull_request: branches: - - master + - main jobs: checkpatch: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbbda0e..36b505d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,15 @@ # Contributing These are recommendations when contributing to the contents of this repository. -They consider contributions to both actual content (mostly Markdown) and support code (demo, lab activities) made via Git. +They consider contributions to both actual content (mostly Markdown) and support code made via Git. ## First Steps Some good first steps and best practices when using Git are explained here: -* the Git Immersion tutorial: https://gitimmersion.com/ -* the Atlassian tutorial: https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud -* this blog post on the ROSEdu Techblog: https://techblog.rosedu.org/git-good-practices.html + +* the Git Immersion tutorial: +* the Atlassian tutorial: +* this blog post on the `ROSEdu Techblog`: ## Language @@ -30,16 +31,22 @@ Use phrases like "find the flag", "run this command", "download the tool". ## Images +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. +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. +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. -For text where no animation is required, use diagrams / images created with [draw.io](https://app.diagrams.net/). -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). - ## Issues When opening an issue, please clearly state the problem. @@ -64,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`. -How a good commit message should look like: https://cbea.ms/git-commit/ -The use of `-s` / `--signoff` when creating a commit is optional, but strongly recommended. +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` + +Signed-off-by: Your Name +``` diff --git a/COPYING.md b/COPYING.md index 57f3c19..e739082 100644 --- a/COPYING.md +++ b/COPYING.md @@ -1,13 +1,13 @@ # License The content of this repository is dual-licensed. -Unless otherwise stated, text content and slides are licensed under the [Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license](https://creativecommons.org/licenses/by-sa/4.0/). -Unless otherwise stated, support code is licensed under the [3-Clause BSD license](https://opensource.org/licenses/BSD-3-Clause) (SPDX short identifier: BSD-3-Clause). +Reading content and slides are licensed under the [Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license](https://creativecommons.org/licenses/by-sa/4.0/). +Support code is licensed under the [3-Clause BSD license](https://opensource.org/licenses/BSD-3-Clause) (SPDX short identifier: BSD-3-Clause). A copy of each license is below. Copy of CC BY-SA 4.0: -``` +```text Attribution-NonCommercial-ShareAlike 4.0 International ======================================================================= @@ -449,7 +449,7 @@ Creative Commons may be contacted at creativecommons.org. Copy of BSD-3-Clause: -``` +```text Copyright 2021 University POLITEHNICA of Bucharest Redistribution and use in source and binary forms, with or without