From 436cff29d25ac37e69e40bec40db20f167ef986b Mon Sep 17 00:00:00 2001
From: Adrian Stoica <stoica@ntnu.no>
Date: Mon, 10 Oct 2022 14:47:54 +0200
Subject: [PATCH] doc: updates slides for lecture 13

---
 lectures/revealjs/13-lecture-commit.adoc | 250 +++++++++++++++++++++++
 1 file changed, 250 insertions(+)
 create mode 100644 lectures/revealjs/13-lecture-commit.adoc

diff --git a/lectures/revealjs/13-lecture-commit.adoc b/lectures/revealjs/13-lecture-commit.adoc
new file mode 100644
index 0000000..19d0d02
--- /dev/null
+++ b/lectures/revealjs/13-lecture-commit.adoc
@@ -0,0 +1,250 @@
+= Planning development tasks and commit strategies
+:customcss: slides.css
+:icons: font
+:includedir: includes/
+:LECTURE_TOPIC: planning dev + committing
+:LECTURE_NO: 13th lecture
+
+include::{includedir}header.adoc[]
+
+
+[.smaller-80][.center-paragraph]
+IT1901 Fall 2022 - {LECTURE_NO}
+
+
+== Overview
+
+- Planning development tasks (issues, branches and commits)
+- Committing strategies and best practices
+- Commit messages
+
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Planning development tasks
+
+- workflow and conventions
+- prevent conflicts and complicated merges
+- run checks before sharing changes		
+
+
+== Workflow and conventions
+
+- agree on workflow and conventions the team is using 
+- have that documented and available in your repository
+** branching strategies
+** branch naming
+** commit message format
+** issue templates
+** MR templates
+** use of labels and boards in gitlab
+
+== Improved workflow (code review) 
+
+- keep master only for finished work
+- uses branches for development work
+- when a feature branch is done a merge request is created
+- code review takes place and more commits happen to address the comments
+- the branch is finally merged into master 
+
+== Gitlab specific push options
+
+- push options
+
+```bash 
+-o merge_request.create 
+-o merge_request.target=my-target-branch 
+-o merge_request.label="Label with spaces"
+```
+
+== Prevent conflicts and complicated merges
+
+- avoid work in different branches with tightly related issues
+- avoid starting in parallel (with different devs) issues that change the same files
+- commit often, small commits that are focused
+- keep up with the main branch in longer lived branches
+
+== Test and check before sharing changes
+
+before pushing (especially to long lived branches like main/master)
+
+- make sure everything builds and runs 
+- verify that the code passes all tests and quality checks 
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Committing strategies and best practices
+
+- small commits dealing with a single topic
+- stage just the changes that are relevant
+- you can stage just part of the changes to a file to include in a commit
+
+== Staging a part of a file changes
+
+- `git add --patch <filename>` 
+- `git add -p <filename>`
+- file is not tracked yet use
+** `git add --intent-to-add <filename>` 
+** `git add -N <filename>`
+- git groups changes into "hunks" and one can select what to include in the next commit
+
+== Staging file parts options (1)
+
+- *y* stage this hunk for the next commit
+- *n* do not stage this hunk for the next commit
+- *q* quit; do not stage this hunk or any of the remaining hunks
+- *a* stage this hunk and all later hunks in the file
+- *d* do not stage this hunk or any of the later hunks in the file
+- *g* select a hunk to go to
+- */* search for a hunk matching the given regex
+
+== Staging file parts options (2)
+
+[.smaller-80]
+- *j* leave this hunk undecided, see next undecided hunk
+- *J* leave this hunk undecided, see next hunk
+- *k* leave this hunk undecided, see previous undecided hunk
+- *K* leave this hunk undecided, see previous hunk
+- *s* split the current hunk into smaller hunks
+- *e* manually edit the current hunk (replace *+* or *-* with *#*)
+- *?* print hunk help
+
+== Things to avoid while committing
+
+- Blending functional and non-functional changes
+- Mixing functional changes that are not related
+- Packing a large change in a single over-sized commit
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Demo
+	
+	
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Commit messages
+
+- common conventions (title, body, footer)
+- conventional commits format
+- what to write in the commit message
+- enforcing commit message format
+- commit hooks  
+
+
+== Commit messages (2)
+
+image::../images/git_commit_2x.png[size=75%]
+[.smaller-40]
+https://xkcd.com/1296/
+
+== Commit messages (seriously)
+
+- Separate subject from body with a blank line
+- Limit the subject line to 50 characters
+- Capitalize the subject line
+- Do not end the subject line with a period
+- Use the imperative mood in the subject line
+- Wrap the body at 72 characters
+- Use the body to explain what and why vs. how
+
+== Conventional commits format
+
+```text
+<type>([optional scope]): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+== More on conventional commit content (1)
+ 
+- fix: a commit of the type fix patches a bug in your codebase 
+- feat: a commit of the type feat introduces a new feature to the codebase 
+- BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change. A BREAKING CHANGE can be part of commits of any type.
+
+== More on conventional commit content (2)
+
+- more types:  build, chore, ci, docs, style, refactor, perf, test
+- footers other than BREAKING CHANGE: `<description>` may be provided and follow a convention similar to git trailer format (`token: value`).
+
+== Why to use the conventional commits?
+
+[.smaller-80]
+- Automatically generating CHANGELOGs.
+- Automatically determining a semantic version bump (based on the types of commits landed).
+- Communicating the nature of changes to teammates, the public, and other stakeholders.
+- Triggering build and publish processes.
+- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
+
+
+== What to write in the commit message
+
+[.smaller-80]
+- the subject line is the most important
+- clearly state the original issue / problem
+- clearly state *why* the change is made
+- minimize external reference use and aim at a self contained message
+- clearly state how the problem is fixed with the committed code 
+- add information about testing, especially if there are manual tests needed  
+
+Finally, read the message before committing as it might reveal that you should split it in smaller commits
+
+== Enforcing commit message format
+
+- use tools such as commitlint and commitizen to check the messages
+- use git hooks check the message format
+- use *Conventional Commits* vscode extension
+
+=== Install Commitizen
+
+- `npm install -g commitizen`
+- `npm install -g cz-conventional-changelog`
+- `echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc`
+
+=== Install Commitlint
+
+- `npm install -g @commitlint/cli @commitlint/config-conventional`
+- `echo "module.exports = {extends: ['@commitlint/config-conventional']}" > ~/commitlint.config.js`
+
+== Commit hooks  
+
+- scripts that run at specific times when running git command
+- can be global (all repositories) or local (the repo they are in)
+- can be used to enforce commit message format
+
+=== git hook example
+
+```bash
+
+#!/bin/bash
+
+echo "Checking commit message: "
+
+# run any local commit-msg hook first
+if test -f ./.git/hooks/commit-msg; then
+	echo "Running local git hook first."
+    sh ./.git/hooks/commit-msg
+else
+	echo "Local hook does not exist."
+fi
+
+commitlint < $1
+
+exit $status
+
+```
+
+[background-color = "#124990"]
+[color = "#fff6d5"]
+== Demo
+
+
+== References
+
+- https://eidson.info/post/using-conventional-commit-messages-globally
+- https://wiki.openstack.org/wiki/GitCommitMessages
+
+
+
+include::{includedir}footer.adoc[]
\ No newline at end of file
-- 
GitLab