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