= 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)
