These are recommendations when contributing to the contents of the Hardware Software Interface OER repository. They consider contributions to both actual content (mostly Markdown) and support code made via Git.
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
All of our content is developed in English. This means we use English for content, support code, commit messages, pull requests, issues, comments, everything.
This section addresses the development of session content and other Markdown files.
Write each sentence on a new line. This way, changing one sentence only affects one line in the source code.
Use the first person plural when writing documentation and tutorials. Use phrases like "we run the command / app", "we look at the source code", "we find the flag".
Use the second person for challenges and other individual activities. Use phrases like "find the flag", "run this command", "download the tool".
Use draw.io 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 are to be written in Markdown, using reveal-md, itself based on reveal-js.
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 drawig is difficult, use draw.io 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.
When opening an issue, please clearly state the problem. Make sure it's reproducible. Add images if required. Also, if relevant, detail the environment you used (OS, software versions). Ideally, if the issue is something you could fix, open a pull request with the fix.
Use GitHub discussions for bringing up ideas on content, new chapters, new sections. Provide support to others asking questions and take part in suggestions brought by others. Please be civil when taking part in discussions.
For pull requests, please follow the GitHub flow: create a fork of the repository, create your own branch, do commits, push changes to your branch, do a pull request (PR).
The destination branch of pull requests is the default master branch.
Make sure each commit corresponds to one code / content change only. If there are multiple commits belonging to a given change, please squash the commits.
Also make sure one pull request covers only one topic.
Before making a commit, configure your name and email locally using:
git config --global user.name "Your Name"
git config --global user.email "[email protected]"Then make sure the email you've just configured corresponds to the one you have set on GitHub.
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:
Signed-off-by: Your Name <[email protected]>
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 name with the chapter and content type it belongs to, e.g. TODO-chapter/reading, TODO-chapter/slides, TODO-chapter/drills.
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".
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: https://cbea.ms/git-commit/ Below is an example of a good commit message:
template-chapter/drills: 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 <[email protected]>
The use of -s / --signoff when creating a commit is optional, but strongly recommended.