diff --git a/lectures/revealjs/15-lecture-commit.adoc b/lectures/revealjs/15-lecture-commit.adoc new file mode 100644 index 0000000000000000000000000000000000000000..cb9094615b7fc8f47538bbc7ca222eec047b68fd --- /dev/null +++ b/lectures/revealjs/15-lecture-commit.adoc @@ -0,0 +1,193 @@ += Planning development tasks and commit strategies +:customcss: slides.css +:icons: font +:includedir: includes/ +:LECTURE_TOPIC: planning dev + committing +:LECTURE_NO: 15th lecture + +include::{includedir}header.adoc[] + + +[.smaller-80][.center-paragraph] +IT1901 Fall 2021 - {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 + + +== 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 + +== 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 + + +== 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) + +- *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: + +- 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 + +- 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 + + +== 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 + +[background-color = "#124990"] +[color = "#fff6d5"] +== Demo + + +include::{includedir}footer.adoc[] \ No newline at end of file