Merge pull request #36 from t4d-gmbh/35-review-2nd-half-of-part-1

Clarified formulation and fixed some typos.

source/content/feature_branch/idea.md

@@ -2,6 +2,6 @@
 
 :::{card}{% if page %} Idea{% endif %}
 
-Create a separate branch for each new feature or change, allowing for independent development and testing.
+Create a separate branch for each new feature or change, allowing for independent, self-contained development and testing.
 
 :::

source/content/feature_branch/index.md

@@ -4,9 +4,9 @@ This section presents one particular development approach with the aim to introd
 
 However, there exists a plethora of approaches, more or less similar to this one and we recommend [Martin Fowler's blog about "Patterns for Managing Source Code Branches"](https://martinfowler.com/articles/branching-patterns.html) for anyone that is interested in learning more about them.
 
-Since we would like to provide an approach that can be used in most cases, we will describe the Feature Branch Approach somewhat loosely, in particular we will not insist of a clear definition of the term feature.
+Since we would like to provide an approach that can be used in most cases, we will describe the *Feature Branch Approach* somewhat loosely, in particular we will not insist of a clear definition of the term *feature*.
 
-In simple terms, the Feature Branch Approach describes:
+In simple terms, the *Feature Branch Approach* describes:
 {% endif %}
 
 
@@ -32,7 +32,7 @@ How to manage and organize changes in a controlled and efficient way.
 ```{include} ./idea.md
 ```
 
-This idea aims to implement the best practice regarding the separation of changes, that is to use aggregate and track changes belonging to a specific subject (or feature in this case) in a dedicated branch.
+This idea aims to implement the best practice regarding the separation of changes, that is to aggregate and track changes belonging to a specific subject (or feature in this case) in a dedicated branch.
 
 ```{include} ./benefits.md
 ```

source/content/principles/healthy_reference.md

@@ -8,9 +8,9 @@ In the <i class="fab fa-git"></i>-context this translates to:
 
 More precisely this state should:
 
-- contain most of the history, i.e. as recent as possible
-- have a minimal chance to contain errors
-- be functional
+- contain most of the history, i.e. as recent as possible.
+- have a minimal chance to contain errors.
+- be functional. Meaning that it should be possible to build and run the software.
 
 {% if slide %}
 ```{toctree}

source/content/principles/separate_best.md

@@ -2,5 +2,5 @@
 
 :::{card} Use branches to isolate changes
 - Agglomerate commits with a similar subject or purpose in a common branch
-- Incorporate branches with completed purpose
+- Incorporate branches with completed purpose, e.g., a feature, a bug fix, or a documentation update is completed in its entirety.
 :::

source/content/principles/states.md

@@ -16,10 +16,11 @@ With <i class="fab fa-git"></i> this translates to:
 ```
 {% else %}
 
-As a developer working the most noticeable _documentation_ activity is writing commit messages.
-Since commit messages strive to explain the introduced changes it can quickly become cumbersome to identify particular states of a repository when solely relying on commit messages. Essentially, when writing only <i class="fab fa-git"></i> commit messages **the state of a repository remains undocumented**.
-
-As a consequence it can become difficult to identify healthy states which is something that can be circumvented by the use of <i class="fab fa-git"></i> tags:
+As a developer, one of your primary tasks is to write clear and concise <i class="fab fa-git"></i> commit messages. 
+These messages are crucial as they explain the changes made. 
+However, relying solely on them can make it difficult to identify specific states of a repository. 
+When writing only <i class="fab fa-git"></i> commit messages, **the state of a repository remains undocumented**. 
+As a result, identifying healthy states can become challenging; however, this issue can be addressed using <i class="fab fa-git"></i> tags.
 
 ```{include} ./states_best.md
 ```

source/content/principles/states_best.md

@@ -2,7 +2,7 @@
 
 :::{card} Regularly tag good states
 - Tag particular states (see [**git tag** {octicon}`link-external;0.8em`](https://git-scm.com/docs/git-tag))
-- Use a meaningful versioning framework to describe states (e.g. [semver {octicon}`link-external;0.8em`](https://semver.org/))
+- Use a meaningful versioning framework to describe states (e.g., [semver {octicon}`link-external;0.8em`](https://semver.org/))
 :::
 
 

source/content/principles/steps.md

@@ -15,9 +15,9 @@ In the <i class="fab fa-git"></i>-world:
 ./steps_best
 ```
 {% else %}
-It is up to the developer to decide how many or few edits go into a commit and, similarly to the [Separate subjects](#separate-subjects), what these changes are about.
+It is the developer's choice how many edits to include in a commit and, as previously mentioned in the section "[*separate subjects*](#separate-subjects), what these changes pertain to.
 
-In addition, commits make up the elementary steps in a git history and can easily be:
+In addition, commits make up the elementary steps in a <i class="fab fa-git"></i> history and can easily be:
 
 - undone (see e.g. [**git revert**&nbsp;{octicon}`link-external;0.8em`](https://git-scm.com/docs/git-revert))
 - applied onto other branches

source/content/principles/steps_best.md

@@ -1,8 +1,11 @@
 ### Best Practice (3/4)
 
 :::{card} Commit small but complete changes
-- Decide what changes to include in a commit (use `git add -p`)
-- Make a commit as specific as possible
-- Write commit messages that specify the purpose of the commit
-- Include as few as possible changes into a commit
+- Decide what changes to include in a commit (use `git add -p`).
+- Make a commit as specific as possible. I.e. include only changes that belong together.
+- Write commit messages that specify the purpose of the commit{% if build == "pages" %} [^sn2] {% endif %}.
+- Include as few as possible changes into a commit. {% if build == "pages" %} Lots of changes make it harder to understand the purpose of the commit. Consider splitting the changes into multiple commits and use branches to isolate changes. {% endif %}
 :::
+{% if build == "pages" %}
+[^sn2]: As a guideline, you can use the [**Conventional Commits**](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+{% endif %}

source/content/versioning/index.md

@@ -7,10 +7,10 @@ One key element of this structure could be a version identifier.
 {% endif %}
 
 [Versioning](https://en.wikipedia.org/wiki/Software_versioning) provides a logical framework for creating labels that represent specific states of a repository.
-{% if page %}By doing so, it establishes a structured way to describe those states.
-The exact logic followed can vary depending on the chosen versioning approach, and there are many to choose from.
+{% if page %} It specifies a structured way to describe those states.
+The specific logic used can differ based on the selected versioning method, and there are numerous options available.
 
-Determining the best versioning approach can be somewhat subjective.
+Choosing the most effective versioning approach can be somewhat subjective. 
 However, certain methods are more widely adopted than others.
 {% endif %}Here, we present one of the most common approaches:
 {% if page %}[SemVer](https://wwww.semver.org).{% endif %}

source/content/versioning/semver.md

@@ -1,6 +1,6 @@
 ## Semantic Versioning
 
-In short SemVer is versioning system that uses a three-part number ({math}`X.Y.Z`) to track changes to your software.
+In short *SemVer* is versioning system that uses a three-part number ({math}`X.Y.Z`) to track changes to your software.
 
 ```{math}
 :label: SemVer
@@ -10,12 +10,12 @@ In short SemVer is versioning system that uses a three-part number ({math}`X.Y.Z
 
 ::::{grid}
 :::{grid-item-card} Major
-Increment when you make breaking changes or significant updates.
+Increment when you make **breaking changes** or **significant updates**.
 :::
 :::{grid-item-card} Minor
-Increment when you add new features or functionality.
+Increment when you add **new features** or **functionality**.
 :::
 :::{grid-item-card} Patch
-Increment when you make bug fixes or minor updates.
+Increment when you make **bug fixes** or **minor updates**.
 :::
 ::::