- a way to ensure and contribute to software quality
- several levels of documentation
[.smaller-60]
Note: In IT1901 we also look if the documentation is original. You should not just copy paste the documentation from the examples and just rename things to match your project.
== Types of documentation
- Design documentation
- API specifications ( if applicable)
- readme files
- contribution guide
- frequently asked questions (faq)
- wiki
- comments ( including Javadoc )
== Who is reading the documentation
- the developer him/herself
- other developers
- future maintainers of the software product
- external users (e.g. some provided API)
- others within the company / institution (testers, deployment )
- ....
== How is documentation improving the quality
- allow new team members to be productive faster
- increase qualities such as maintainability and transferability
- saves time for both other contributors and initial dev
== Readme files (1)
- give overview information regarding a project, subproject, module
- normally contains info about the role, contents, build details, dependencies and interactions with other parts / modules
== Readme files (2)
- can contain information such as setting up environment, installing dependencies and other needed software, building, running the project
- it is a way to provide needed contextual information that otherwise is not apparent from just looking at the source code
== Comments (1)
- allow adding documentation in close proximity with the code
- they should not be a way to cope with bad naming or "special" assumptions in the code
- the standardized comments such as JavaDoc allow additional benefits such as code completion
- can be tracked using source code management tools
- do not depend on a specific editing sofware
[background-color = "#124990"]
[color = "#fff6d5"]
== Markdown
== Markdown
[.center-paragraph]
Markdown is a lightweight markup language with plain text formatting syntax. Its design allows it to be converted to many output formats, but the original tool by the same name only supports HTML. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.
- it is easier to modify and we do not need any special editors
- it can be versioned same way as the code
- holding documentation in the repository and updating it will allow consulting the repository contents with the correct documentation for that snapshot in time
== Plant UML
- open source tool for UML diagrams
- it takes a textual description and produces a diagram
- supported within markdown in GitLab
- uses Graphviz to lay out the diagrams
== Adding diagrams to markdown
[source, role="stretch"]
----
```plantuml
class LatLong {
double latitude
double longitude
}
class LatLongs
LatLongs *--> "*" LatLong: "latLongs"
class MetaData
LatLong *--> "1" MetaData: "metaData"
```
----
[background-color = "#124990"]
[color = "#fff6d5"]
== Commit messages
== Commit messages
- Commit messages allow the developers to attach a description to the commits.
- overview of the project history
- the better the commits messages the easiest is to navigate the project history and understand what happened
== Commit message anatomy
- Subject / Title - Essence of the commit in a few words
- Body - Extended textual description of what has been done
- Footer - Additional elements such as links to issues and other metadata
== Basic principles
[.smaller-80]
- be consistent
- limit the subject line to 50 characters
- don't put a period at the end of the subject line
- put a blank line between the subject line and the body text
- wrap the body text at 72 characters
- use the imperative mood
- describe *what* and *why*, but not *how*
- mention which component(s) / area changed.
== Commit messages (2)
image::../images/git_commit_2x.png[size=75%]
[.smaller-40]
https://xkcd.com/1296/
== 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
